bereniketech/api-vs-mcp-decision

API vs. MCP Decision

1. The Core Trade-off

| Dimension | MCP Server | Direct API / CLI | |-----------|-----------|-----------------| | Token cost | High — full tool schema loads every session | Low — only the call you make | | Discovery | Claude sees all available tools | Claude only does what you wire up | | Flexibility | Any operation the server exposes | Only the endpoints you hardcode | | Setup cost | One-time install, reusable | Per-task wiring | | Best for | Multi-operation workflows, unknown scope | Single known operation, token-tight sessions |

Rule: If you'll use only one endpoint from a service in a given project, use a direct API call. MCP is for breadth of access, not depth.

2. Decision Tree

Do you know exactly which operation you need?
├── Yes → Will you call it more than 3 times per session?
│   ├── No  → Direct API call (hardcoded endpoint)
│   └── Yes → Do you need more than 2 operations from this service?
│             ├── No  → Direct API helper function
│             └── Yes → MCP server
└── No  → MCP server (let Claude discover available tools)

3. When to Use MCP

• You need Claude to discover what's possible (e.g., explore a Notion workspace, browse GitHub issues)
• The task requires 3+ different operations on the same service
• The MCP server is already installed and context window isn't tight
• You're building a reusable workflow others will run

4. When to Use Direct API / CLI

• You need exactly one operation (e.g., read one database, post one message)
• Context window is tight — MCP tool schemas eat 200–2000 tokens per server
• The CLI tool has a simpler interface than the MCP equivalent (e.g., bq query, gh pr list)
• You're in a sub-agent that only needs one fact — use Haiku + direct call, not Opus + MCP

5. Hardcoding Direct Calls

For a scoped operation, write a small wrapper rather than loading the MCP server:

# Instead of: load full Notion MCP → browse → find → read
import requests

def read_notion_db(db_id: str, token: str) -> list:
    headers = {"Authorization": f"Bearer {token}", "Notion-Version": "2022-06-28"}
    r = requests.post(f"https://api.notion.com/v1/databases/{db_id}/query", headers=headers)
    return r.json().get("results", [])

Rule: One function, one service, one purpose. No MCP overhead for a single known query.

6. Context Budget Reality Check

Each MCP server loaded adds roughly:

• Small server (5–10 tools): ~500–1000 tokens/session
• Large server (20+ tools): ~2000–5000 tokens/session

With 10 MCP servers enabled: up to 30,000 tokens consumed before the first message. Keep active MCPs ≤ 5 for token-sensitive work.