I added MCP servers to Claude Code. Here's what they cost in tokens.

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.

What MCP tool definitions actually look like in your context

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>

Enter fullscreen mode Exit fullscreen mode

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 measured three real MCP server configurations

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.

The compounding problem in agentic loops

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:

• Tool definition overhead: ~6.2M tokens
• At Sonnet 4 input pricing: ~$18.60 in overhead alone
• That’s before any actual work tokens, cache misses, or output

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.

How to measure it yourself

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.

# rough per-turn input token average for your last session
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)}')
"

Enter fullscreen mode Exit fullscreen mode

If your average input tokens per turn is much higher than the actual content you’re passing, tool definitions are likely the culprit.

Three things you can do right now

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.

The broader pattern

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.