Cuppa.ai

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-server

Codex: codex mcp add cuppa --env CUPPA_API_KEY=cpa-your-key -- … · Add to Cursor · Claude Desktop, Windsurf and other MCP clients use this config:

mcp.json
{
  "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

Node.js 20+
npm i -g @cuppa-ai/cli
cuppa auth login --key cpa-your-key
cuppa auth status

No install:

export CUPPA_API_KEY=cpa-your-key
npx @cuppa-ai/cli auth status

Every 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.

List your brands
curl -s https://api.cuppa.ai/v1/sites \
  -H "X-API-KEY: cpa-your-key"
Add a brand
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

  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.

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

  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 and their commands

JobMCP toolCLIREST
SEO articlescreate_contentcuppa generate "best project management tools"POST /v1/contents
Brand DNAcreate_sitecuppa site create --domain yourcompany.comPOST /v1/sites
Keyword and SERP researchresearch_keywordscuppa research keywords -k "email marketing for dentists"POST /v1/research/keywords
Ad creativecompetitor_adscuppa brand ads --domain competitor.comPOST /v1/brand/competitor-ads
UGC video adsgenerate_ugc_adcuppa brand ugc --script "<45-75 words>" --character <image-url> --voice <voice-url> [--confirm]POST /v1/brand/ugc
Social posts and schedulinggenerate_social_multicuppa social multi -s <site-id> -p linkedin,twitter --article-title "<title>" --article-summary "<summary>"POST /v1/social/multi
Brand imagesgenerate_imagecuppa image generate -s <site-id> -p "<prompt>"POST /v1/images
Brand videogenerate_video_scriptcuppa video create -p "<prompt>" -m replicate:seedance-2.0-fastPOST /v1/video/script
AI visibility and search performanceget_brand_performancecuppa performance overviewGET /v1/performance/overview
Website auditrun_website_auditcuppa website-audit runPOST /v1/performance/website-audit
Programmatic and local SEO pagescreate_pagecuppa seo local --service "roof repair" --locations cities.txt --research-serpsPOST /v1/pages
PR pitches and newslettersscan_pr_opportunitiescuppa --helpPOST /v1/pr/scan
Brand listening and reviewslisten_brand_mentionscuppa brand listen --brand "Your Brand" --domain yourcompany.comPOST /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." } }.

StatusMessageFixRetry
401Invalid 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.
403No active subscription found
The team has no active plan or trial.
A human starts a plan or trial in the app.Do not retry.
400Anthropic 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.
404Not 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.
429Rate 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.

PlanMonthlyAnnualBrandsSeats
Solo$119/mo$99/mo, billed $1,188/yr1 brand1 seat
Studio$249/mo$199/mo, billed $2,388/yr3 brandsUp to 3 seats
Scale$449/mo$369/mo, billed $4,428/yr10 brandsUp to 10 seats
Enterprise$1,099/mo$899/mo, billed $10,788/yrUp to 20 brandsUp 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