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

```bash
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:

```json
{
  "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:

```bash
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](https://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.

***