Everyone talks about MCP servers as a way to extend Claude Code. Fewer people talk about what they cost.
Every MCP tool you register injects a tool-definition block into your context window on every single turn. That's not a one-time cost — it compounds across your entire session. I wanted to know the actual numbers, so I measured them.
When Claude Code loads an MCP server, it reads the server's tool manifest and injects something like this into the system prompt:
<tool>
name: read_file
description: Read the contents of a file at the given path...
inputSchema: { type: object, properties: { path: { type: string } }, required: ["path"] }
</tool>
That's roughly 80–150 tokens per tool, depending on how verbose the description and schema are. A server with 10 tools = 800–1,500 tokens added to every turn of your session.
I ran sessions with three different MCP server setups and tracked the token breakdown using tokenscope-mcp — an MCP server that exposes Claude Code's own .jsonl
cost data back to the agent so you can inspect it mid-session.
Here's what I found across 20-turn sessions:
| MCP server | Tools registered | Tokens/turn (tool defs) | 20-turn session overhead |
|---|---|---|---|
| No MCP | 0 | 0 | 0 |
| Custom minimal server | 3 | ~180 | ~3,600 |
| filesystem (official) | 7 | ~640 | ~12,800 |
| github (official) | 26 | ~3,100 | ~62,000 |
The GitHub MCP server — which many people add by default — costs ~62,000 tokens of overhead per 20-turn session, before you've asked it to do anything. At Claude Sonnet 4 input pricing ($3/MTok), that's roughly $0.19 in pure tool-definition overhead per session.
That doesn't sound like much. But if you're running long agentic loops — the kind where Claude Code is doing multi-step tasks autonomously — you're paying that overhead on every single turn, including turns where the agent never touches GitHub at all.
In a standard interactive session, you might do 20–30 turns. In an autonomous agent loop running overnight, you might do 500–2,000 turns.
At 2,000 turns with the GitHub MCP server loaded:
This is exactly the dynamic behind the "136M tokens doing almost nothing" pattern. The agent isn't being wasteful in any obvious way — it's paying a per-turn tax on every tool it could use, whether it uses them or not.
The .jsonl
session logs that Claude Code writes to ~/.claude/projects/
contain per-turn token breakdowns. You can inspect the input_tokens
field across turns and watch it stay elevated even on turns where the agent just reads a file.
cat ~/.claude/projects/**/*.jsonl | \
python3 -c "
import sys, json
turns = [json.loads(l) for l in sys.stdin if l.strip()]
inputs = [t.get('usage',{}).get('input_tokens',0) for t in turns if 'usage' in t]
print(f'turns: {len(inputs)}, avg input tokens/turn: {sum(inputs)//max(len(inputs),1)}')
"
If your average input tokens per turn is much higher than the actual content you're passing, tool definitions are likely the culprit.
1. Use project-scoped MCP configs.
Claude Code supports .mcp.json
at the project level. Create different configs for different task types — a writing config with no GitHub server, a code-review config with filesystem only, etc. Don't load every server for every session.
2. Prefer MCP servers with fewer, more focused tools.
A server with 3 well-scoped tools costs 6–8× less overhead than one with 26 broad tools. When evaluating MCP servers, tool count is a real cost signal.
3. If you write MCP servers, keep descriptions tight.
A 400-token tool description vs. an 80-token one is a 5× difference in per-turn overhead across every session that loads your server. The schema matters too — avoid deeply nested optional fields that inflate the JSON schema block.
MCP is genuinely useful. I'm not arguing against it. But the cost model is non-obvious: you pay for registered tools, not called tools. Every tool definition rides along in your context whether the agent uses it or not.
Once you see that, the right mental model shifts from "add MCP servers for capabilities I might want" to "add MCP servers for capabilities I'm actively using in this session."
*I track per-turn token costs using tokenscope (CLI) and tokenscope-mcp (MCP server). Both read Claude Code's native *
.jsonl
logs — no proxy, no API key, no modified client.