API, MCP or CLI

CLI vs MCP vs API: Which Should I Use?

Cuppa offers three programmatic interfaces: the CLI, the MCP server, and the REST API. They all hit the same backend, use the same API key, and write to the same database. The difference is how you interact with them.

Quick Comparison

	CLI	MCP Server	REST API
Best for	Terminal workflows, AI agents with shell access, scripting	AI editors (Cursor, Claude Desktop, Windsurf)	Custom integrations, automation platforms
Interface	Shell commands	AI client tools (auto-discovered)	HTTP requests
Setup	`npm install -g @cuppa-ai/cli`	JSON config in AI client	Direct HTTP calls
Output	Tables or JSON	Structured text for AI reasoning	JSON
Auth	`cuppa auth login` or `CUPPA_API_KEY` env var	`CUPPA_API_KEY` in config	`X-API-KEY` header
Commands/Tools	75+ commands	75+ tools	70+ endpoints
Workflow commands	Yes (generate, optimize, publish, campaign, seo)	No (primitives only)	No (primitives only)
Interactive	Yes (prompts, spinners, progress)	No	No
Plan required	Solo+	Solo+	Solo+

When to Use the CLI

Use the CLI when:

Your AI agent has terminal/shell access (Claude Code, Cursor terminal, any CLI-based AI)
You want high-level workflow commands that chain multiple operations (generate + grade, optimize + SERP research, full campaign creation)
You are scripting content operations in bash, CI/CD pipelines, or cron jobs
You want interactive feedback like progress spinners, formatted tables, and colored output
You are a power user who prefers terminal over browser

Example:

cuppa generate "content marketing strategy" --model gpt-5 --grade
cuppa seo local --service "plumbing" --locations cities.txt --research-serps
cuppa campaign create --type mixed --images 5 --videos 3 --publish

When to Use the MCP Server

Use the MCP server when:

You work inside an AI editor (Cursor, Claude Desktop, Windsurf, Cline)
You want your AI assistant to call Cuppa tools inline while you are coding or writing
You prefer conversational interaction (“generate an article about X using my Brand DNA”)
You want tool auto-discovery where the AI client finds available tools automatically

Example:

{
  "mcpServers": {
    "cuppa": {
      "command": "npx",
      "args": ["-y", "@cuppa-sh/mcp-server"],
      "env": { "CUPPA_API_KEY": "your-key" }
    }
  }
}

Then ask your AI assistant: “Using Cuppa, generate an article about cloud migration best practices and grade it for SEO.”

When to Use the REST API

Use the REST API when:

You are building a custom integration (your own app, dashboard, or tool)
You are connecting to automation platforms (Zapier, Make, n8n)
You are building ChatGPT Actions or custom GPTs
You need fine-grained control over every request and response
Your programming language is not JavaScript (the API is language-agnostic)

Example:

curl -X POST "https://api.cuppa.ai/v1/contents" 
  -H "X-API-KEY: your-key" 
  -H "Content-Type: application/json" 
  -d '{"site_id": "abc", "target_keyword": "content marketing"}'

OpenAPI spec: cuppa.ai/static/cuppa-api-v1.yaml

Can I Use More Than One?

Yes. They all share the same backend:

Create an article via CLI, edit it in the Cuppa web app, publish it via MCP
Grade content via the REST API, optimize it via the CLI
Use MCP for day-to-day work in your editor, CLI for batch operations in scripts

Everything syncs. One API key unlocks all three interfaces.

MCP Read Me I have ChatGPT, will that work with Cuppa?