MCP vs CLI: What Tool Definitions Really Cost Your Agent's Context Window
MCP vs CLI comes down to when your agent pays for a tool. An MCP server sends every tool's name, description and JSON Schema to the model before you type anything. A CLI costs nothing until the agent runs it and reads its --help or output. On a measured setup, four common MCP servers added 11,923 tokens of tool definitions; the Apidog CLI skill added 112.
That gap is the whole story behind two Dev.to posts this week. One developer typed "Run tests" into a coding agent and saw 28,400 input tokens on the first request, with no files attached and no history. The culprit was seven MCP servers. Another argued that MCP is dead simple to build, and that the hard parts (auth, approvals, duplicate calls) start right after the demo works.
This article stays on one question: what do tool definitions cost your context window, and when does a CLI the agent calls on demand cost less? If your problem is huge tool responses instead, read the companion piece on trimming bloated API responses.
Why MCP servers use context window tokens
An MCP server advertises its tools through the tools/list method. Per the MCP tools specification, each tool carries a name, a description and an inputSchema (a JSON Schema for its arguments). For the model to pick a tool, the client has to put those definitions into the request. In a classic setup, that happens on every turn of every conversation, whether the agent calls the tool or not.
So the cost grows with three things:
- Tool count. A full GitHub integration can expose dozens of tools.
- Schema depth. Nested objects, enums and long descriptions all become tokens.
- Turns. An agent loop sends the definitions again on each step.
The necoz post puts numbers on it: a 52-tool stack cost 24,600 tokens of schema on turn 1, against 640 tokens for a 4-tool setup, and about 246,000 tokens across a 10-step loop. Treat those as one developer's measurement, not a benchmark. Prompt caching cuts the dollar cost of repeated definitions, but the tokens still occupy the window and compete with your code for attention.
There's a quality cost too. Anthropic's tool search documentation says a multi-server setup with GitHub, Slack, Sentry, Grafana and Splunk "can consume ~55k tokens in definitions before Claude does any work", and that Claude's tool selection accuracy degrades once you pass 30 to 50 available tools.
MCP tool definition tokens: a measurement you can repeat
On 2026-11-16 I started five MCP servers locally over stdio, sent initialize and tools/list from a 30-line Node script, and counted the tokens in each tool's name, description and inputSchema.
One caveat up front: I counted with OpenAI's tiktoken o200k_base encoding because it runs offline. Claude, Gemini and other models use their own tokenizers, so your counts will differ by some margin. The ratios between setups are what matter here.
| MCP server (version) | Tools | Definition tokens | Avg per tool |
|---|---|---|---|
@playwright/mcp 0.0.85 | 25 | 4,634 | 185 |
@modelcontextprotocol/server-filesystem 2.3.0 | 16 | 3,281 | 205 |
@modelcontextprotocol/server-memory 2.1.1 | 9 | 2,013 | 224 |
@modelcontextprotocol/server-everything 2.3.0 | 16 | 1,995 | 125 |
| Those four together | 66 | 11,923 | 181 |
apidog-mcp-server 0.0.18 | 3 | 291 | 97 |
Four ordinary servers cost about 12,000 tokens before the agent reads a file.
The last row is the useful counterexample. The Apidog MCP server exposes three narrow tools (read the project's OpenAPI spec, read $ref files, refresh the spec), so it costs 291 tokens. Tool count and schema depth drive the bill, not the protocol.
For the CLI side, I measured what an agent actually reads when it uses Apidog CLI 2.2.12:
| CLI text | When it enters context | Tokens |
|---|---|---|
| Apidog CLI skill description (frontmatter) | Every session, as a skill listing | 112 |
| Apidog CLI skill body | Only when the task matches | 1,189 |
apidog --help | Only when the agent runs it | 668 |
apidog test-case --help | Only when the agent runs it | 511 |
apidog run --help | Only when the agent runs it | 1,036 |
The always-on cost of the CLI route is 112 tokens. Even if the agent loads the full skill and reads three help pages, it lands near 3,500 tokens, and only in the conversation that needs it.
MCP vs CLI: the token cost comparison
| MCP server (definitions loaded upfront) | CLI called through the shell | |
|---|---|---|
| Upfront cost | Every tool's schema, every turn | Zero, or a short skill description |
| Discovery | Structured tools/list | --help text, read when needed |
| Output | Whatever the tool returns | Whatever the command prints (you can filter it) |
| Works across clients | Any MCP client, one config | Any agent with a shell tool |
| Typed arguments | Yes, via JSON Schema | Flags; payload files validated separately |
| Auth and permissions | Server's job (OAuth for remote HTTP servers) | Your local login and shell permissions |
The CLI wins on upfront cost because the agent already has a shell tool. Running apidog endpoint list --project 123 uses the Bash tool it was going to load anyway. The MCP route wins when you need the same capability in several clients without writing an integration for each, which is the point Sylwia Lask makes: MCP isn't a replacement for REST, it's a standard way for AI clients to discover and call tools.
Your client may already defer MCP tools
Before you rip out every server, check what your agent does. The cost above assumes definitions load upfront. Some clients no longer do that by default.
Claude Code's MCP documentation says tool search is enabled by default: "Only tool names and server instructions load at session start", and full definitions load when Claude searches for them. You control it with ENABLE_TOOL_SEARCH:
- unset or
true: MCP tools are deferred and loaded on demand -
auto: tools load upfront while their definitions total under 10% of the context window -
auto:N: the same, with your own percentage -
false: every MCP tool loads upfront
Two exceptions matter. Models earlier than Opus 4 and Sonnet 4 load MCP tools upfront regardless, and a server set to alwaysLoad: true skips deferral. Run /context in Claude Code to see which tools are marked deferred. On the Claude API itself, the same idea is the tool search tool: you set defer_loading: true on tools that shouldn't load upfront, and Anthropic says it typically cuts definition tokens by over 85%.
Deferral fixes definition cost, not output cost: Claude Code warns when an MCP tool returns more than 10,000 tokens and caps output at 25,000 by default (MAX_MCP_OUTPUT_TOKENS). New to the protocol? Start with what MCP is and why it matters for APIs.
When to use MCP vs CLI for API work
For API design, testing and docs, use this split:
- Use a CLI when the task is something you'd run in a terminal anyway: list endpoints, export an OpenAPI file, create and run a test case, run a suite in CI. The agent pays for help text only when it needs it, and you can pipe output through
jqor--reportersto keep it short. - Use a narrow MCP server when the agent needs structured read access every turn, such as reading your OpenAPI spec while writing client code. Three tools at 291 tokens is a fair price.
- Avoid leaving five or more servers enabled globally across every project. That's the setup that produced the 28,400-token "Run tests".
Whichever you pick, Sylwia's warnings still apply: a tool that writes data needs server-side permission checks, a human approval step for risky actions, and duplicate detection so a rerun doesn't create the same record twice.
Let your coding agent drive Apidog CLI
Here's the CLI route for API work, with your coding agent doing the typing. Install the CLI, log in once and add the agent skill:
npm install -g apidog-cli@latest apidog auth login --with-token <YOUR_TOKEN> npx -y skills add https://apidog.com # pick your agent when prompted You can also tell the agent "Read https://apidog.com/apidog-cli-installation-guide.md and set up Apidog CLI", and it follows the agent-friendly install guide.
Then give it one prompt:
In Apidog project 123, list the endpoints, export the spec as OpenAPI 3.1 to ./openapi.json, then create a test case for GET /users/{id} that asserts a 200 status and an id field, run it against environment 456 and summarize failures. Read --help for each command before using it. Print only the lines you need. The agent reads help as it goes, validates its JSON, then runs the case:
apidog endpoint list --project 123 --page 1 --page-size 500 apidog export --project 123 --format openapi --oas-version 3.1 --output ./openapi.json apidog cli-schema get test-case-create apidog cli-schema validate test-case-create --file case.json apidog test-case create --project 123 --file case.json apidog run --test-case <caseId> --project 123 -e 456 -r cli,json Each command returns structured JSON, often with agentHints.nextSteps, so the agent knows what to run next without loading a schema for every possible action. The same apidog run ... -r junit line drops into CI, as shown in the Apidog CLI CI/CD pipeline guide. For a Claude Code walkthrough, see Apidog CLI in Claude Code, and for measured tool-call savings, 30% fewer tool calls, 25% fewer tokens.
To see every command group before you start, read the Apidog CLI page.
How to cut MCP token cost today
- Run
/contextin Claude Code (or your client's equivalent) and note the tool-definition total. - Move servers you don't need from global config to project config.
- Turn on deferred loading (
ENABLE_TOOL_SEARCHin Claude Code). - Replace broad servers with a CLI plus a short skill for terminal-shaped work.
- For servers you build, keep tools few and descriptions short.
FAQ
Do MCP tools use tokens if the agent never calls them? In a client that loads definitions upfront, yes. Every tool's name, description and input schema go into each request. Clients with deferred loading, like Claude Code with tool search on, send only tool names until a tool is needed.
How many tokens does an MCP server use? It depends on tool count and schema depth. In my measurement, @playwright/mcp used 4,634 tokens for 25 tools and the Apidog MCP server used 291 for 3 tools, counted with the o200k_base tokenizer.
Is a CLI always cheaper than MCP for AI agents? Upfront, almost always, because the agent reuses its shell tool. Per call, a CLI can still flood context if the agent prints a large payload, so filter output either way.
Does prompt caching fix MCP context bloat? It lowers the price of repeated definitions. It doesn't free the context window, and the model still attends to those tokens on every turn.
Should I stop using MCP servers? No. Use narrow servers for structured, every-turn access and for sharing one capability across clients. Move terminal-shaped API work, like exports and test runs, to a CLI.




