---
name: cuppa
description: "Marketing tools for agents via Cuppa AI: brand DNA, SEO articles, keyword/SERP research, ad creative, UGC video ads, social posts and scheduling, on-brand images and video, PR pitches, website audits, GSC/Bing/AI-visibility performance. Use when the user asks for marketing content or research for a brand or domain."
homepage: https://cuppa.ai
version: 0.2.0
---

# Cuppa AI

Marketing tools for agents via Cuppa AI: brand DNA, SEO articles, keyword/SERP research, ad creative, UGC video ads, social posts and scheduling, on-brand images and video, PR pitches, website audits, GSC/Bing/AI-visibility performance. Use when the user asks for marketing content or research for a brand or domain.

## When to use

- The user wants marketing work done for a specific brand or domain: articles, ads, images, video, social posts, research or performance data.
- Not for: generic copy with no brand, or tools listed under "Not offered" below.

## Setup

Check for `CUPPA_API_KEY`. If it is missing, ask the human for one: they create it at https://app.cuppa.ai/team/settings/api/keys (any plan, 7-day trial) and connect at least one AI provider key at https://app.cuppa.ai/team/settings/keys. You cannot create accounts or keys yourself.

MCP (preferred in editors):
```bash
claude mcp add cuppa -e CUPPA_API_KEY=cpa-your-key -- npx -y @cuppa-ai/mcp-server
```
CLI (shell agents; `--format json` on every command):
```bash
npm i -g @cuppa-ai/cli
cuppa auth status
```
REST: `https://api.cuppa.ai/v1`, header `X-API-KEY`. Spec: https://cuppa.ai/openapi.json

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

- SEO articles: `create_content` / `cuppa generate "best project management tools"`
- Brand DNA: `create_site` / `cuppa site create --domain yourcompany.com`
- Keyword and SERP research: `research_keywords` / `cuppa research keywords -k "email marketing for dentists"`
- Ad creative: `competitor_ads` / `cuppa brand ads --domain competitor.com`
- UGC video ads: `generate_ugc_ad` / `cuppa brand ugc --script "<45-75 words>" --character <image-url> --voice <voice-url> [--confirm]`
- Social posts and scheduling: `generate_social_multi` / `cuppa social multi -s <site-id> -p linkedin,twitter --article-title "<title>" --article-summary "<summary>"`
- Brand images: `generate_image` / `cuppa image generate -s <site-id> -p "<prompt>"`
- Brand video: `generate_video_script` / `cuppa video create -p "<prompt>" -m replicate:seedance-2.0-fast`
- AI visibility and search performance: `get_brand_performance` / `cuppa performance overview`
- Website audit: `run_website_audit` / `cuppa website-audit run`
- Programmatic and local SEO pages: `create_page` / `cuppa seo local --service "roof repair" --locations cities.txt --research-serps`
- PR pitches and newsletters: `scan_pr_opportunities` / `cuppa --help`
- Brand listening and reviews: `listen_brand_mentions` / `cuppa brand listen --brand "Your Brand" --domain yourcompany.com`

For flags, run `cuppa <command> --help`; for tool arguments, read the MCP tool schema. Do not guess parameters.

## Costs

Flat plan fee (Solo $119/mo, Studio $249/mo, Scale $449/mo, Enterprise $1,099/mo). AI usage is billed by the user's own providers with zero markup. Video and UGC jobs quote before spending.

## Errors

- 401: 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).
- 403: The team has no active plan or trial. A human starts a plan or trial in the app.
- 400: 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).
- 404: Wrong id, or the resource belongs to another team or brand. List first (GET /v1/sites, GET /v1/contents) and use a returned id.
- 429: Over the per-second cap (Solo 5/s, others 10/s) or an endpoint limit. Back off until X-RateLimit-Reset.

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

More: https://cuppa.ai/developers.md · https://cuppa.ai/llms.txt
