MCP vs CLI Token Trade-off
The architectural decision between using an MCP server (which loads all tool definitions into context) versus a direct CLI or API endpoint (which loads nothing until called), with significant implications for context efficiency.
Key points
- MCP servers load their entire tool-definition catalogue into the context window at session start [src-011]
- If only one or two capabilities are needed, hardcoding a direct API endpoint or CLI command saves all those definition tokens [src-011]
- Playwright CLI vs Chrome DevTools MCP: Nate switched after /context showed the MCP consuming a disproportionate share of token budget [src-011]
- Notion example: if you only need to read one database, a hardcoded REST endpoint beats loading the full Notion MCP [src-011]
- Core principle: match the tool surface area to the actual task surface area [src-011]
- Marco Mornati’s GitHub experiment adds measured data: Native MCP had the lowest per-operation cost, but its about 3,062-token fixed schema overhead made it dramatically more expensive in a 20-prompt session with only two GitHub operations [src-041]
- The best architecture depends on service-use frequency, captured by the G/N Ratio Tool Selection heuristic [src-041]
Decision guide
| Use MCP when… | Use CLI/API directly when… |
|---|---|
| You need many of the MCP’s capabilities | You need only 1–2 specific endpoints |
| The MCP provides complex OAuth/auth management | Auth is simple (API key) |
| You don’t control the underlying system | You can call the API directly |
| The service is used on most prompts | The service is rare or session-bookend work |
| You want native typed schemas and can amortize them | You can use On-Demand Skill Files or a Gateway MCP Pattern |
Related entities
- Playwright CLI — the CLI chosen over Chrome DevTools MCP for browser automation
- Context7 MCP — an MCP that is worth loading because it covers thousands of libraries (full surface area benefit)
Related concepts
- Context Rot — MCP token overhead contributes to context bloat
- Claude Code Context Management Discipline — token trade-off decisions are a key lever
- Model Context Protocol (MCP) — the MCP specification itself
- Tool Schema Tax — fixed schema overhead paid even when a tool is idle
- Gateway MCP Pattern — lazy-schema alternative that keeps structured output with lower idle cost
Source references
- [src-011] Nate Herk — Claude Code power features cluster (2026-04-20 to 2026-04-27)
- [src-013] Nate Herk — “Build & Sell Claude Code Operating Systems (2+ Hour Course)” (2026-05-01)
– API-over-MCP applied to ClickUp: “I want to use ClickUp’s API because it’s more token efficient than having the MCP server. Create me a reference guide, a markdown file inside of this project that has all of the endpoints stored so that later if you need to use a different one, you don’t have to go do research again.”
- [src-041] Marco Mornati — “The Future of Agentic Tooling: MCP Servers vs. CLI A Data-Driven Comparison” (2026-04-27)
Recommended next
Keep reading from this thread
From 477 indexed pages and articles.
- Wiki concept Progressive Context Loading (Skills) The three-level loading pattern Claude Code uses to keep skills lightweight. Level 1: initial search only reads the YAML frontmatter (name + Related by cli
- Wiki concept Browser Automation with Claude Code The pattern of connecting a browser automation CLI (Playwright) to Claude Code so it can control a real browser — navigating Related by cli
- Insight AI Beyond POCs How enterprise AI moves beyond proofs of concept through ownership, governance, measurement, adoption, and production operating models Readers have engaged with this next