Developers
Cuppa AI for developers: MCP server, CLI and REST API
One MCP server, CLI and REST API for brand DNA, SEO articles, ad creative, UGC video, social posts, brand images and video. Bring your own AI keys, zero markup. The same API key works for all three, on every plan.
@cuppa-ai/mcp-server@0.2.0@cuppa-ai/cli@0.1.8https://api.cuppa.ai/v1
Quickstart (MCP)
Claude Code, one command:
claude mcp add cuppa -e CUPPA_API_KEY=cpa-your-key -- npx -y @cuppa-ai/mcp-serverCodex: codex mcp add cuppa --env CUPPA_API_KEY=cpa-your-key -- … · Add to Cursor · Claude Desktop, Windsurf and other MCP clients use this config:
{
"mcpServers": {
"cuppa": {
"command": "npx",
"args": [
"-y",
"@cuppa-ai/mcp-server"
],
"env": {
"CUPPA_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.
First prompt: “Use Cuppa to add my brand yourcompany.com, then show me its brand DNA and suggest 5 article ideas.”
Per-client guides: Claude Code · Cursor · Codex · Claude Desktop · Windsurf · ChatGPT
CLI
npm i -g @cuppa-ai/cli
cuppa auth login --key cpa-your-key
cuppa auth statusNo install:
export CUPPA_API_KEY=cpa-your-key
npx @cuppa-ai/cli auth statusEvery command supports --format json. Run cuppa --help or cuppa <command> --help for flags.
REST API
Base URL https://api.cuppa.ai/v1. Send your key in the X-API-KEY header.
curl -s https://api.cuppa.ai/v1/sites \
-H "X-API-KEY: cpa-your-key"curl -s -X POST https://api.cuppa.ai/v1/sites \
-H "X-API-KEY: cpa-your-key" \
-H "Content-Type: application/json" \
-d '{"domain":"yourcompany.com"}'OpenAPI 3.1: /openapi.yaml · /openapi.json
Authenticate with an API key
- A human signs up for any plan at app.cuppa.ai (7-day free trial).
- They connect at least one AI provider key (BYOK) at https://app.cuppa.ai/team/settings/keys.
- They create a Cuppa AI API key (starts with cpa-) at https://app.cuppa.ai/team/settings/api/keys.
- They give that key to the agent as CUPPA_API_KEY. REST calls send it in the X-API-KEY header.
Agents can’t create accounts or keys. If CUPPA_API_KEY is missing, the agent should ask the human for one.
MCP, CLI or REST?
- MCP in editors and chat clients (181 tools, stdio (runs locally via npx)).
- CLI in shell agents, CI and scripts.
- REST in servers, automations (Zapier, Make) and custom GPT Actions.
Core loop
- 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).
- Read brand DNA before writing anything: get_brand / cuppa brand get <siteId> / GET /v1/sites/{id}/brand.
- Do the job (article, image, ad, video, social post) against that site id.
- Long jobs are async: poll the status tool or endpoint until done.
Jobs and their commands
| Job | MCP tool | CLI | REST |
|---|---|---|---|
| SEO articles | create_content | cuppa generate "best project management tools" | POST /v1/contents |
| Brand DNA | create_site | cuppa site create --domain yourcompany.com | POST /v1/sites |
| Keyword and SERP research | research_keywords | cuppa research keywords -k "email marketing for dentists" | POST /v1/research/keywords |
| Ad creative | competitor_ads | cuppa brand ads --domain competitor.com | POST /v1/brand/competitor-ads |
| UGC video ads | generate_ugc_ad | cuppa brand ugc --script "<45-75 words>" --character <image-url> --voice <voice-url> [--confirm] | POST /v1/brand/ugc |
| Social posts and scheduling | generate_social_multi | cuppa social multi -s <site-id> -p linkedin,twitter --article-title "<title>" --article-summary "<summary>" | POST /v1/social/multi |
| Brand images | generate_image | cuppa image generate -s <site-id> -p "<prompt>" | POST /v1/images |
| Brand video | generate_video_script | cuppa video create -p "<prompt>" -m replicate:seedance-2.0-fast | POST /v1/video/script |
| AI visibility and search performance | get_brand_performance | cuppa performance overview | GET /v1/performance/overview |
| Website audit | run_website_audit | cuppa website-audit run | POST /v1/performance/website-audit |
| Programmatic and local SEO pages | create_page | cuppa seo local --service "roof repair" --locations cities.txt --research-serps | POST /v1/pages |
| PR pitches and newsletters | scan_pr_opportunities | cuppa --help | POST /v1/pr/scan |
| Brand listening and reviews | listen_brand_mentions | cuppa brand listen --brand "Your Brand" --domain yourcompany.com | POST /v1/brand/listen |
Provider keys (BYOK)
AI usage runs on your own provider keys, connected at Team Settings → Provider API Keys. Cuppa AI adds no markup.
- 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)
If a job needs a provider you haven’t connected, the API returns 400 naming the provider. Add the key, 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
Every error has the shape { "error": { "status": 401, "message": "Invalid or missing API key." } }.
| Status | Message | 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 foundThe 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 foundWrong 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. |
Pricing
Two separate costs. (1) A flat Cuppa AI plan fee, below. (2) AI usage, billed to you directly by your own AI providers (OpenAI, Anthropic, Google, Replicate, Perplexity, xAI) at their published rates. Cuppa AI adds zero markup and does not bill usage.
| Plan | Monthly | Annual | Brands | Seats |
|---|---|---|---|---|
| Solo | $119/mo | $99/mo, billed $1,188/yr | 1 brand | 1 seat |
| Studio | $249/mo | $199/mo, billed $2,388/yr | 3 brands | Up to 3 seats |
| Scale | $449/mo | $369/mo, billed $4,428/yr | 10 brands | Up to 10 seats |
| Enterprise | $1,099/mo | $899/mo, billed $10,788/yr | Up to 20 brands | Up to 30 seats |
7-day free trial on every plan. Fair-use policy on all plans. API, CLI and MCP access is included on every plan, including Solo. Full pricing
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.
Machine-readable
- /llms.txt: annotated index of every page
- /skill.md and /.well-known/skills
- /developers.md: this page as Markdown (every page has a .md twin)
- /pricing.json
- Guides: learn.cuppa.ai