---
title: "Cuppa AI for developers: MCP server, CLI and REST API"
url: https://cuppa.ai/developers
description: "Install the Cuppa AI MCP server or CLI, authenticate with an API key, rate limits and error codes."
updated: 2026-11-18
mcp_server: @cuppa-ai/mcp-server@0.2.0
cli: @cuppa-ai/cli@0.1.8
---
# Cuppa AI for developers: MCP server, CLI and REST API

Current versions: `@cuppa-ai/mcp-server@0.2.0` (181 tools, stdio (runs locally via npx)) and `@cuppa-ai/cli@0.1.8` (`cuppa`, Node.js 20+). REST base URL: https://api.cuppa.ai/v1.

## Authentication (a human does this once)

1. A human signs up for any plan at app.cuppa.ai (7-day free trial).
2. They connect at least one AI provider key (BYOK) at https://app.cuppa.ai/team/settings/keys.
3. They create a Cuppa AI API key (starts with cpa-) at https://app.cuppa.ai/team/settings/api/keys.
4. They give that key to the agent as CUPPA_API_KEY. REST calls send it in the X-API-KEY header.

## Connect an agent



Claude Code:

```bash
claude mcp add cuppa -e CUPPA_API_KEY=cpa-your-key -- npx -y @cuppa-ai/mcp-server
```

Codex:

```bash
codex mcp add cuppa --env CUPPA_API_KEY=cpa-your-key -- npx -y @cuppa-ai/mcp-server
```

Cursor, Claude Desktop, Windsurf (mcp.json):

```json
{
  "mcpServers": {
    "cuppa": {
      "command": "npx",
      "args": [
        "-y",
        "@cuppa-ai/mcp-server"
      ],
      "env": {
        "CUPPA_API_KEY": "cpa-your-key"
      }
    }
  }
}
```

CLI:

```bash
npm i -g @cuppa-ai/cli
cuppa auth login --key cpa-your-key
cuppa auth status
```

REST:

```bash
curl -s https://api.cuppa.ai/v1/sites \
  -H "X-API-KEY: cpa-your-key"
```

Verify: `cuppa auth status` prints your team and key status. In MCP, ask the agent to call `list_sites`; it should return your brands.

## Which one to use

- MCP: in editors and chat clients (Claude Code, Cursor, Codex, Claude Desktop, Windsurf).
- CLI: in shell agents and scripts. Every command supports `--format json`; run `cuppa <command> --help`.
- REST: in servers and automations. Send `X-API-KEY`.

First prompt to try: "Use Cuppa to add my brand yourcompany.com, then show me its brand DNA and suggest 5 article ideas."

## Core loop

1. Resolve the brand: `list_sites` (MCP) / `cuppa site list` / `GET /v1/sites`. Create one with a domain if none exists (`create_site` / `cuppa site create --domain` / `POST /v1/sites`).
2. Read brand DNA before writing anything: `get_brand` / `cuppa brand get <siteId>` / `GET /v1/sites/{id}/brand`.
3. Do the job (article, image, ad, video, social post) against that site id.
4. Long jobs are async: poll the status tool or endpoint until done.

## Jobs

| Job | MCP tools | CLI | REST |
| --- | --- | --- | --- |
| [SEO articles](https://cuppa.ai/use-cases/seo-content-api-for-ai-agents.md) | create_content, get_content_status, grade_content | `cuppa generate "best project management tools"` | POST /v1/contents |
| [Brand DNA](https://cuppa.ai/use-cases/brand-dna-api-for-ai-agents.md) | create_site, get_brand, update_brand_context | `cuppa site create --domain yourcompany.com` | POST /v1/sites |
| [Keyword and SERP research](https://cuppa.ai/use-cases/keyword-research-api-for-ai-agents.md) | research_keywords, research_serp, research_competitors | `cuppa research keywords -k "email marketing for dentists"` | POST /v1/research/keywords |
| [Ad creative](https://cuppa.ai/use-cases/ad-creative-api-for-ai-agents.md) | competitor_ads, generate_ad, get_ad_batch_status | `cuppa brand ads --domain competitor.com` | POST /v1/brand/competitor-ads |
| [UGC video ads](https://cuppa.ai/use-cases/ugc-video-ad-api-for-ai-agents.md) | generate_ugc_ad, find_creators | `cuppa brand ugc --script "<45-75 words>" --character <image-url> --voice <voice-url> [--confirm]` | POST /v1/brand/ugc |
| [Social posts and scheduling](https://cuppa.ai/use-cases/social-media-scheduling-api-for-ai-agents.md) | generate_social_multi, generate_carousel, schedule_social | `cuppa social multi -s <site-id> -p linkedin,twitter --article-title "<title>" --article-summary "<summary>"` | POST /v1/social/multi |
| [Brand images](https://cuppa.ai/use-cases/on-brand-image-generation-api-for-ai-agents.md) | generate_image, generate_images_bulk, generate_mood_board | `cuppa image generate -s <site-id> -p "<prompt>"` | POST /v1/images |
| [Brand video](https://cuppa.ai/use-cases/brand-video-generation-api-for-ai-agents.md) | generate_video_script, create_video, get_video_status | `cuppa video create -p "<prompt>" -m replicate:seedance-2.0-fast` | POST /v1/video/script |
| [AI visibility and search performance](https://cuppa.ai/use-cases/ai-visibility-tracking-api-for-ai-agents.md) | get_brand_performance, get_bing_performance, get_ai_visibility | `cuppa performance overview` | GET /v1/performance/overview |
| [Website audit](https://cuppa.ai/use-cases/website-audit-api-for-ai-agents.md) | run_website_audit, get_website_audit, get_website_audit_opportunities | `cuppa website-audit run` | POST /v1/performance/website-audit |
| [Programmatic and local SEO pages](https://cuppa.ai/use-cases/programmatic-seo-api-for-ai-agents.md) | create_page, get_page_status, create_serp_cluster_bulk | `cuppa seo local --service "roof repair" --locations cities.txt --research-serps` | POST /v1/pages |
| [PR pitches and newsletters](https://cuppa.ai/use-cases/pr-pitch-api-for-ai-agents.md) | scan_pr_opportunities, generate_pr_pitch, list_pr_contacts | `cuppa --help` | POST /v1/pr/scan |
| [Brand listening and reviews](https://cuppa.ai/use-cases/brand-monitoring-api-for-ai-agents.md) | listen_brand_mentions, scan_reviews, enrich_company | `cuppa brand listen --brand "Your Brand" --domain yourcompany.com` | POST /v1/brand/listen |

## Provider keys (BYOK)

- OpenAI: articles, chat, social copy, images, Link Engine embeddings
- Anthropic: articles, chat, social copy
- Google (Gemini): articles, chat, images
- Replicate: images (Flux, Nano Banana Pro) and video (Seedance and others)
- Perplexity: live web research (optional)
- xAI: Grok models (optional)
- Connect at https://app.cuppa.ai/team/settings/keys. If a job needs a provider that is not connected, the API returns 400 with the provider name; ask the human to add it, or pick a model from `GET /v1/meta/models` whose provider is connected.

## Rate limits

- All plans: hard cap of 10 requests/second per key.
- Solo: 5 requests/second per team.
- Some endpoints add their own limits (for example a website audit run is once per hour).
- 429 responses include X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (ms epoch). Wait until reset, then retry.

## Errors

Shape: `{ "error": { "status": 401, "message": "Invalid or missing API key." } }`

| Status | Message | Cause | Fix | Retry |
| --- | --- | --- | --- | --- |
| 401 | Invalid or missing API key. | No X-API-KEY header, a key that does not start with cpa-, or a revoked key. | Create a key at https://app.cuppa.ai/team/settings/api/keys and send it as X-API-KEY (or CUPPA_API_KEY for the CLI and MCP). | Do not retry until the key is fixed. |
| 403 | No active subscription found | The team has no active plan or trial. | A human starts a plan or trial in the app. | Do not retry. |
| 400 | Anthropic API key is missing. Add one in Team Settings → API Keys. (or the OpenAI/Replicate equivalent) | The job needs a provider key the team has not connected (BYOK). | A human adds the provider key at https://app.cuppa.ai/team/settings/keys, or the agent picks a model whose provider is connected (GET /v1/models). | Retry after the key is added. |
| 404 | Not found | Wrong id, or the resource belongs to another team or brand. | List first (GET /v1/sites, GET /v1/contents) and use a returned id. | Do not retry the same id. |
| 429 | Rate limit exceeded. Please wait N seconds. | Over the per-second cap (Solo 5/s, others 10/s) or an endpoint limit. | Back off until X-RateLimit-Reset. | Safe to retry after the reset time. |

## Reference

- OpenAPI: https://cuppa.ai/openapi.yaml (JSON: https://cuppa.ai/openapi.json)
- MCP server: https://www.npmjs.com/package/@cuppa-ai/mcp-server
- CLI: https://www.npmjs.com/package/@cuppa-ai/cli
- Guides: https://learn.cuppa.ai
- Per-client setup: https://cuppa.ai/agents/claude-code.md, https://cuppa.ai/agents/cursor.md, https://cuppa.ai/agents/codex.md, https://cuppa.ai/agents/claude.md, https://cuppa.ai/agents/windsurf.md, https://cuppa.ai/agents/chatgpt.md

## Not offered

- No hosted (remote) MCP connector. The MCP server runs locally via npx.
- No keyless plan and no usage credits: you must connect your own AI provider key (BYOK).
- No Azure OpenAI keys.
- ChatGPT Plus or Claude Pro subscriptions are not API access and cannot be used as BYOK keys.
- No Notion, HubSpot, Semrush, Surfer SEO or Clearscope integrations.
- No agent self-signup: a human creates the account and the API key.

---

Index of every Markdown page: https://cuppa.ai/llms.txt · Setup: https://cuppa.ai/developers.md · Pricing: https://cuppa.ai/pricing.md
