The Hidden Context Tax of MCP

Adding an MCP server feels free. One line in .mcp.json and your agent can suddenly touch GitHub, your filesystem, a database. But every tool that server exposes ships its full definition — name, description, and JSON input schema — into the model's context on every turn, before you type a single prompt. That's not free. It's a tax you pay continuously, it compounds with every server you add, and almost nobody measures it.

We've been linting the agent-config surface for a while — permissions, CLAUDE.md, .mcp.json server shapes, the lethal trifecta across grants. This one isn't a safety check. It's a measurement: how much of your context window is gone before any work starts?

The numbers are bigger than you'd guess

This isn't a hypothetical. The evidence is sitting in Anthropic's own engineering posts and issue tracker:

• A Claude Code user measured their MCP tools eating 98.7k tokens — 49.3% of a 200k window — before doing anything. Google-docs alone was ~25k across 34 tools; Asana ~30k across 40+.
• Anthropic's "Code Execution with MCP" post opens by noting agents now load "all tool definitions upfront directly into context," and shows one workflow dropping from 150,000 tokens to 2,000 once they stopped doing that.
• Their Tool Search work cites a stack of 58 tools ≈ 55k tokens before the conversation starts, and recommends acting once tool definitions cross ~10k tokens or 10+ tools. Fewer tools also measurably improved selection accuracy (Opus 4: 49% → 74%).

The cost is real, it's large, and it's the reason Anthropic built deferred-loading at all. So we wrote the thing that tells you your number.

mcp-budget

It connects to your MCP servers the way a client does — JSON-RPC over stdio, initialize then tools/list — serializes each tool exactly as it'd be sent to the model, and counts the tokens.

$ mcp-budget
mcp-budget — context tax of 5 MCP server(s)  (est. ~4 chars/token)

  ≈ 4,249 tok  ( 2.1% of 200k)  github  — 26 tool(s)
           largest tool: create_pull_request_review ≈ 436 tok
  ≈ 2,043 tok  ( 1.0% of 200k)  filesystem  — 14 tool(s)
  ≈ 1,248 tok  ( 0.6% of 200k)  git  — 12 tool(s)
  ≈ 1,105 tok  ( 0.6% of 200k)  memory  — 9 tool(s)
  ≈ 1,020 tok  ( 0.5% of 200k)  sequentialthinking  — 1 tool(s)
           largest tool: sequentialthinking ≈ 1,020 tok

  ● ≈9,665 tokens across 62 tool(s) — 4.8% of a 200k window spent before your first prompt.

Those are real definitions pulled from the live reference servers, not estimates from a catalog. And look at the last line: sequentialthinking is one tool that costs 1,020 tokens — as much as the entire 9-tool memory server. Its "description" is a 900-word instruction manual the model reads every turn. Which is the whole point:

Tool count is not context cost. A server with one verbose tool can outweigh a server with a dozen lean ones. You can't eyeball this from .mcp.json; you have to measure the definitions.

Why not just read /context?

Claude Code has a /context readout, so why a separate tool? Because /context over-reports MCP cost. It counts each tool against the shared tool-use system prompt and sums, double-counting that fixed overhead once per tool — one server showed ~45k reported vs ~15k actual, roughly 3× inflated (a number later Claude Code versions corrected). The honest figure is the size of the definitions you actually ship: the serialized {name, description, input_schema}, summed once. That's exactly what mcp-budget counts, which makes its number a truer floor than the inflated readout — and it works for any MCP client, not just Claude Code.

A caveat we keep visible in the tool: the token count is an estimate (~4 chars/token; Claude's exact tokenizer isn't public). It's a budgeting signal, not a billing figure. The relative weights — which server, which tool is heavy — are what you act on, and those are robust.

Putting it in CI

The footprint only grows: one autopsy watched the GitHub MCP server's tax climb from 42k to 55k tokens in six months as features were added — "the context tax compounds with feature velocity." So mcp-budget takes a budget and exits non-zero when you blow it:

$ mcp-budget --budget 8000
  ● ≈9,665 tokens … 4.8% of a 200k window spent before your first prompt.
  ✗ over budget: ≈9,665 > 8,000 tokens.
$ echo $?
1

Drop that in a pre-commit hook or CI step and a newly-added server that balloons your context fails the build instead of silently eating 5% of every conversation. --json gives you the structured numbers for dashboards.

The tax is also the attack surface

Here's the part that makes this more than a budgeting nicety. The text you're counting — every tool description, every field name in the schema — is un-authored instruction text sitting in the model's context, indistinguishable to the model from instructions you wrote. That's not our framing; it's the basis of tool-poisoning attacks, where a malicious server hides directives in a tool's description, and OWASP's note that every part of the tool schema is a potential injection point, not just the description. Whoever writes that window writes the model's instructions.

So the token count is a proxy for two things at once: how much context you're spending, and how much un-vetted instruction surface you've imported. A 9,665-token MCP footprint is 9,665 tokens of someone else's text the model treats as authoritative. Trimming servers you don't use buys back context and shrinks the injection surface in the same move.

What we landed on

The actionable habit is small: measure the tax, don't assume it's free. Before you leave five MCP servers wired up out of convenience, run the number. If it's north of Anthropic's ~10k / 10-tool threshold, prune to the servers this project actually needs, prefer lean tools over kitchen-sink ones, and let clients that support deferred tool-loading (Claude Code's Tool Search) carry the rest. The convenience of MCP is real — but so is the bill, and now you can read it.

mcp-budget is a single file, no dependencies — point it at your .mcp.json and see your number. → Talk to us if you're tuning an agent's context budget.

---

Prior art, credited: Anthropic's "Code Execution with MCP" and "Tool Search" posts quantified and tackled this first; PolicyLayer's calculator catalogs server costs statically. mcp-budget's niche is the live, client-agnostic measurement: connect to any stdio MCP server and count the real serialized definitions, with a CI gate. It's an estimate, not a billing figure — treat the relative weights as the signal.

---

Get the tool → mcp-budget in agent-ops — open source (MIT), a single dependency-free script, part of our toolkit for running coding agents in production.