MCP
MCP Server
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 45+ 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
Go to Team Settings > API Keys
Click Create Key
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):
Claude Desktop
Add to your claude_desktop_config.json:
Config file locations:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
Windsurf / Cline / Other MCP Clients
Same pattern. Point to npx -y @cuppa-sh/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"
Your AI assistant selects the right Cuppa tools automatically based on your request.
Available Tools (45+)
Content Creation
create_content
Generate an AI article from a keyword
update_content
Update an existing article
get_content_status
Poll article generation progress
get_content
Retrieve a generated article
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
Content Grading and SEO
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
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
research_keywords
Keyword research from seed terms
research_serp
SERP analysis for a keyword
research_competitors
Competitor content analysis
research_cluster
Topic cluster research
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
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
generate_social
Generate social media posts
publish_social
Publish a post immediately
schedule_social
Schedule a post for later
list_social_platforms
List connected social platforms
list_social_posts
List social posts
get_social_post
Get a social post
update_social_post
Update a social post
delete_social_post
Delete a social post
generate_carousel
Generate a multi-slide carousel
publish_carousel
Publish a carousel
Images and Video
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
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
Clusters
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
list_sites
List your brands/sites
create_site
Create a new site
get_gsc_queries
Get Google Search Console data
Research Agents
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
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
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
create_page
Create a page from a template
get_page
Get page details
get_page_status
Check page generation status
list_pages
List pages
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."
Environment Variables
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:
Content generation, images, social
Solo
Knowledge sources
Power
Content grading and SERP
Power
Research agents
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.
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: 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
Support: [email protected]
Last updated
Was this helpful?