# MCP ## MCP Server The Cuppa MCP (Model Context Protocol) server lets AI clients like Cursor, Claude Desktop, Windsurf, and Cline access Cuppa natively. Your AI assistant can generate articles, grade content, manage Brand DNA, run research agents, and publish to your CMS, all from inside your editor. *** ### What Is MCP? MCP (Model Context Protocol) is an open standard that lets AI clients call external tools. When you add the Cuppa MCP server to your AI client, it discovers 75+ tools automatically. You can then ask your AI assistant to use Cuppa in natural language. *** ### Requirements * **Node.js 18+** (needed for `npx`) * **Cuppa account** on Solo plan or higher * **Cuppa API key** (created in Team Settings) * **An MCP-compatible AI client** (Cursor, Claude Desktop, Windsurf, Cline) *** ### Setup #### Step 1: Create an API Key 1. Go to [Team Settings > API Keys](https://app.cuppa.ai/team/settings/api/keys) 2. Click **Create Key** 3. Copy the key (starts with `cpa-`) #### Step 2: Configure Your AI Client **Cursor** Add to `.cursor/mcp.json` in your project root (or global Cursor config): ```json { "mcpServers": { "cuppa": { "command": "npx", "args": ["-y", "@cuppa-ai/mcp-server"], "env": { "CUPPA_API_KEY": "cpa-your-key-here" } } } } ``` **Claude Desktop** Add to your `claude_desktop_config.json`: ```json { "mcpServers": { "cuppa": { "command": "npx", "args": ["-y", "@cuppa-ai/mcp-server"], "env": { "CUPPA_API_KEY": "cpa-your-key-here" } } } } ``` Config file locations: * **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` * **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` **Windsurf / Cline / Other MCP Clients** Same pattern. Point to `npx -y @cuppa-ai/mcp-server` with the `CUPPA_API_KEY` environment variable. #### Step 3: Restart Your AI Client After adding the config, restart your AI client. The Cuppa tools will be auto-discovered. #### Step 4: Verify Ask your AI assistant: > "Using Cuppa, list my sites." If it returns your brand list, you are connected. *** ### Using Cuppa in Your AI Client Once connected, just ask your AI assistant to do things with Cuppa in natural language: * "Generate an article about content marketing best practices using my Brand DNA" * "Grade this article for SEO and tell me what to improve" * "Run my content gap research agent" * "Publish this article to Ghost and create a LinkedIn post" * "What are my top-performing keywords this month?" * "Create a bulk project with 20 articles targeting these keywords" * "Update my brand context with these new guidelines" * "What topics are trending in my industry right now?" * "Research what content formats are working on LinkedIn for SaaS brands" * "Check my social analytics, find trending topics, then create posts for the best opportunities" Your AI assistant selects the right Cuppa tools automatically based on your request. *** ### Available Tools (75+) #### Content Creation | Tool | Description | | -------------------- | ------------------------------------------------------------------- | | `create_content` | Generate an AI article from a keyword | | `update_content` | Update title, HTML content, meta description, or target keyword | | `export_content` | Get full article HTML without truncation (for saving to disk) | | `get_content_status` | Poll article generation progress | | `get_content` | Retrieve a generated article (paginated HTML, 8K default) | | `list_contents` | List articles with filters | | `delete_content` | Delete an article | | `publish_content` | Publish to Ghost, Webflow, Sanity, Contentful, Shopify, or Airtable | | `import_content` | Import an article from a URL | | `parse_brief` | Parse a content brief into structured article generation parameters | #### Content Grading and SEO | Tool | Description | | ------------------- | --------------------------------------------------- | | `grade_content` | Trigger SEO and readability grading | | `get_content_grade` | Get grading results with scores and recommendations | | `fetch_serp_data` | Trigger SERP competitor analysis | | `get_serp_data` | Get SERP analysis results | | `optimize_content` | Get AI-powered optimization suggestions | #### Bulk Generation | Tool | Description | | ---------------- | ------------------------------------------------------- | | `create_project` | Create a bulk generation project with multiple articles | | `list_projects` | List projects | | `get_project` | Get project details and progress | | `export_project` | Export completed project articles | #### Research and Trend Discovery | Tool | Description | | ------------------------------ | ------------------------------------------------------------------------------- | | `research_keywords` | Keyword research from seed terms | | `research_serp` | SERP analysis for a keyword | | `research_competitors` | Competitor content analysis | | `research_cluster` | Topic cluster research | | `research_trends` | Google Trends: rising queries, breakout topics, trend direction, YouTube trends | | `research_web` | Web search via Perplexity Sonar Pro for real-time trends and industry news | | `create_serp_cluster_bulk` | Bulk SERP clustering | | `get_serp_cluster_bulk_status` | Check bulk clustering status | | `generate_from_serp_clusters` | Generate content from clusters | #### Brand DNA and Knowledge | Tool | Description | | --------------------------- | ------------------------------ | | `get_brand` | Get Brand DNA for a site | | `update_brand_context` | Update brand context fields | | `update_brand_visual_style` | Update colors, fonts, logo | | `get_notebook` | List brand notebook entries | | `list_knowledge` | List knowledge sources | | `create_knowledge` | Create a text knowledge source | | `get_knowledge` | Get knowledge source details | #### Social Media | Tool | Description | | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `generate_social` | Generate social post (from article or standalone topic) | | `generate_social_multi` | Multi-platform post generation | | `create_social_content` | Generate + schedule/publish in one step | | `publish_social` | Publish a new post immediately | | `schedule_social` | Schedule a new post for later | | `schedule_social_draft` | Schedule an existing draft post via Late.dev (uses the post's scheduled time) | | `publish_social_draft` | Publish an existing draft post immediately via Late.dev | | `bulk_schedule_social_drafts` | Schedule or publish multiple draft posts at once (up to 50) | | `list_social_platforms` | List connected social platforms | | `list_social_posts` | List social posts with analytics | | `get_social_post` | Get social post details with analytics | | `update_social_post` | Update a social post | | `delete_social_post` | Delete a social post | | `get_social_analytics` | Live social analytics: impressions, engagements, reach, followers, best posting times, content decay, top posts with links | | `generate_carousel` | Generate a multi-slide carousel | | `publish_carousel` | Publish a carousel | #### Images and Video | Tool | Description | | ----------------------- | ----------------------------- | | `generate_image` | Generate an AI image | | `generate_images_bulk` | Bulk image generation | | `generate_video_script` | Generate a video script | | `create_video` | Create a video from a script | | `get_video_status` | Check video generation status | | `delete_video` | Delete a video | #### Content Planning & Strategy | Tool | Description | | ------------------------- | ------------------------------------------------- | | `list_planner` | List content planner items | | `create_planner_item` | Add an item to the content plan | | `update_planner_item` | Update a planner item | | `delete_planner_item` | Remove a planner item | | `list_planner_events` | List holidays, custom dates, events | | `create_planner_event` | Add custom dates to the planner | | `delete_planner_event` | Remove planner events | | `get_content_calendar` | Unified calendar (articles + local + social) | | `get_content_strategy` | Get content strategy settings | | `update_content_strategy` | Update article defaults, social, newsletter, etc. | #### Clusters | Tool | Description | | -------------------- | --------------------------- | | `generate_cluster` | Generate a topic cluster | | `list_clusters` | List clusters | | `get_cluster` | Get cluster details | | `activate_cluster` | Add cluster to content plan | | `deactivate_cluster` | Remove cluster from plan | #### Sites and Analytics | Tool | Description | | ----------------- | ------------------------------ | | `list_sites` | List your brands/sites | | `create_site` | Create a new site | | `get_gsc_queries` | Get Google Search Console data | #### Research Agents | Tool | Description | | ------------------- | ------------------------------------- | | `list_agents` | List your research agents | | `get_agent` | Get agent details with latest results | | `trigger_agent_run` | Trigger a manual agent run | #### Presets, Templates, and Links | Tool | Description | | ----------------------------------------------------------------------------------- | --------------------------- | | `list_presets` / `get_preset` / `create_preset` / `update_preset` / `delete_preset` | Manage content presets | | `list_templates` / `get_template` | Browse custom templates | | `get_link_stats` / `get_link_categories` | Link Engine data | | `list_models` / `list_image_models` | Available AI models | | `chat` | Brand-aware chat completion | #### Mood Board | Tool | Description | | --------------------- | ------------------------------- | | `list_mood_boards` | List mood boards | | `create_mood_board` | Create a mood board | | `get_mood_board` | Get mood board details | | `delete_mood_board` | Delete a mood board | | `generate_mood_board` | Auto-generate mood board images | #### Pages | Tool | Description | | ----------------- | ----------------------------- | | `create_page` | Create a page from a template | | `get_page` | Get page details | | `get_page_status` | Check page generation status | | `list_pages` | List pages | #### Performance Hub | Tool | Description | | ----------------------- | ------------------------------------------------------------ | | `get_brand_performance` | KPIs, Brand Visibility Score, and quick wins | | `get_content_health` | Top pages, content decay, striking distance, cannibalization | | `get_ai_visibility` | LLM mentions, top prompts, cited pages, citation gaps | | `get_backlinks` | Domain rating, backlink stats, referring domains via Ahrefs | #### Newsletters | Tool | Description | | --------------------- | -------------------------------------------------- | | `list_newsletters` | List generated newsletters | | `get_newsletter` | Get newsletter with full content and HTML | | `generate_newsletter` | Generate weekly newsletter from published articles | *** ### Example Workflows #### Generate and publish an article > "Using Cuppa, generate an article about sustainable packaging for ecommerce on my default site. When it's done, grade it for SEO and publish it to Ghost." #### Run a research agent and create content from findings > "Trigger my content gap agent. When it finishes, show me the brief and generate articles for the top 3 opportunities." #### Bulk content production > "Create a Cuppa project with 15 articles targeting these keywords: \[list]. Use my 'Blog Post' preset." #### Brand management > "Show me my Brand DNA. Update the brand context to mention that we now offer free shipping on all orders." #### Performance analysis > "Pull my full brand performance from the Cuppa Performance Hub. What are my quick wins? Show me any content decay and striking distance keywords." #### Data-driven social content (The Content Loop) > "Check my social analytics to see what's working. Then research trending topics in my niche using Google Trends and web search. Use those insights plus my Brand DNA to create social posts for LinkedIn and X, and schedule them at the best posting times." This workflow follows the Content Loop: Measure (analytics) -> Research (trends) -> Context (brand) -> Create -> Schedule -> Iterate. #### Trend research > "What topics are trending in AI marketing right now? Check Google Trends for the past 7 days and do a web search for what content formats are going viral on LinkedIn." The `research_trends` tool uses Google Trends (via DataForSEO) for rising queries, breakout topics, and trend direction. The `research_web` tool uses Perplexity Sonar Pro with focus modes: `social_trends`, `industry_news`, or `competitor_analysis`. Requires a Perplexity API key in Team Settings. #### Newsletter generation > "Generate a newsletter from this week's published articles on my default site. Show me the result." *** ### Environment Variables | Variable | Required | Description | | --------------- | -------- | ------------------------------------------------------- | | `CUPPA_API_KEY` | Yes | Your Cuppa API key (starts with `cpa-`) | | `CUPPA_API_URL` | No | Override API base URL (default: `https://api.cuppa.ai`) | *** ### Plan Requirements The MCP server works on Solo plans and above. Some tools require higher plans: | Feature | Minimum Plan | Notes | | ---------------------------------- | ------------ | --------------------------------------- | | Content generation, images, social | Solo | | | Knowledge sources | Power | | | Content grading and SERP | Power | | | Research agents | Power | | | Trend research (`research_trends`) | Power | Uses DataForSEO Google Trends | | Web research (`research_web`) | Power | Requires Perplexity API key in settings | | Performance Hub overview | Power | | | AI Visibility data | Business | | | Backlinks (Ahrefs) | Power | | | Newsletters | Power | | | Link Engine | Business | | | Custom templates | Business | | | Brand Notebook | Scale | | *** ### Everything Syncs All content created via the MCP server is stored in your Cuppa account. Articles, images, social posts, and planner items created from your AI editor appear in the Cuppa web app immediately. *** ### MCP Resources The MCP server also exposes resources that can be saved directly to disk without entering the AI context window. This is useful for exporting full article HTML without truncation. | Resource URI | Type | Description | | ----------------------------- | ----------- | ------------------------------ | | `cuppa://content/{articleId}` | `text/html` | Full article HTML body content | In Cursor, use `FetchMcpResource` with the `downloadPath` parameter to save an article directly: ``` FetchMcpResource({ server: "cuppa", uri: "cuppa://content/", downloadPath: "content/blog/my-article.html" }) ``` This writes the complete HTML to your local filesystem, bypassing context window limits entirely. *** ### Troubleshooting **"CUPPA\_API\_KEY environment variable is required"** Make sure your API key is set in the `env` section of your MCP config. The key should start with `cpa-`. **Tools not appearing in your AI client** Restart the AI client after adding the config. Check that Node.js 18+ is installed (`node --version`). **"Access denied. Please upgrade your plan"** The tool you are using requires a higher plan tier. Check the plan requirements table above. **AI assistant does not use Cuppa tools** Try being explicit: "Using Cuppa, ..." or "Call the Cuppa MCP tool to ..." Some AI clients need a direct mention to trigger tool use. *** ### Also Available * **Cuppa CLI**: Terminal commands for scripting, CI/CD, and AI agents with shell access * [**REST API**](https://cuppa.ai/static/cuppa-api-v1.yaml): Direct HTTP calls for custom integrations and automation platforms * **CLI vs MCP vs API**: Comparison guide to choose the right interface All three interfaces use the same API key and write to the same database. *** ### Need Help? * **Documentation**: [learn.cuppa.ai](https://learn.cuppa.ai) * **Support**: