Claude Code token overhead: what 33k actually costs
TL;DR: Claude Code sends roughly 30,000 tokens before it reads a word of your prompt. We measured 29,061 from an empty directory with MCP off, and 38,805 inside a real project. Two things about that number matter. Prompt caching makes it cost about a cent and a half per request rather than fifteen. And the popular claim that each MCP server piles on tens of thousands of tokens is wrong — we measured 27 tokens per deferred tool.
How many tokens does Claude Code send before your prompt?
About 30,000. Here’s the measurement, from an empty directory, asking Claude Code to reply with the single word ok:
| Setup | Prompt tokens |
|---|---|
| Empty directory, MCP disabled | 29,061 |
| Empty directory, one MCP server | 29,079 |
| Empty directory, three MCP servers | 29,567 |
| Empty directory, our usual MCP setup | 30,411 |
| Inside our own project repo | 38,805 |
Claude Code v2.1.226, Opus 5, macOS, measured August 10, 2026. “Prompt tokens” is input_tokens + cache_creation_input_tokens + cache_read_input_tokens — the whole prefix the model reads, however it’s billed. The one-server row exposes a single tool. The three-server row had two of the three connect, exposing four tools between them. Our usual setup is three servers and 51 tool names.
That floor is the system prompt, the built-in tool schemas, and the harness scaffolding. It’s fixed, and you pay it on every single request in the session, because the whole conversation gets resent each turn.
So the 33k figure that reached Hacker News in July, from a post by Systima measuring Claude Code against OpenCode, is the right order of magnitude. A commenter on that thread pushed back with a /context readout from a fresh session showing 23k — 3.9k system prompt, 13.9k system tools, 4.9k skills. Both are true. They’re measuring different installs, and a different model: that readout is Opus 4.8.
How to measure your own startup overhead
One command. No instrumentation, no proxy:
cd /tmp && mkdir -p ctxtest && cd ctxtest
claude -p "Reply with exactly: ok" --output-format json | python3 -c "
import sys, json
u = json.load(sys.stdin)['usage']
print(u['input_tokens']
+ u.get('cache_creation_input_tokens', 0)
+ u.get('cache_read_input_tokens', 0))"Run it from an empty directory for your floor on that machine — user-level CLAUDE.md and skills still load, so it isn’t a clean-install number — then from your project root for your real one. The gap between the two is what your own configuration costs you. Add --strict-mcp-config to exclude user-scoped MCP servers and isolate them.
Here’s what came back on a fresh run of exactly that command, which landed on 29,061 again:
input_tokens: 2 — and that the cached tokens sit under ephemeral_1h, which is what tells you Claude Code is using the 1-hour TTL.That output makes the trap visible. Don’t read input_tokens alone: it’s the uncached remainder only, so here it reads 2 while the prefix the model actually read is 29,061. That single field is where a lot of the confused numbers in this discussion come from.
Do MCP servers really add 50,000 tokens?
Not in a default setup. The figure circulating in MCP roundups and forum threads is 50,000 to 70,000 tokens per session for Model Context Protocol servers, and our measurements are two orders of magnitude below it.
Connecting one server exposing a single tool cost 18 tokens. Our full user-scoped set — three servers, 51 tool names between them — cost 1,350 tokens, going by the table above. (We ran that configuration twice, at 30,411 and 30,433; the second run puts it at 1,372.)
The mechanism is tool search, on by default. Anthropic’s docs are specific about what loads at session start: “Only tool names and server instructions load at session start.” The full JSON schema is fetched when a task actually needs that tool.
Those two words — server instructions — matter more than they look, and they explain an oddity in our own table. Two connected servers exposing four tools cost 506 tokens. Fifty-one tool names cost 1,350. That’s 127 per tool in the first case and 26 in the second, which makes no sense as a per-tool rate. It makes perfect sense once you split it: each server pays a fixed cost for its instructions block (Claude Code truncates those at 2KB), and each tool then adds a name. So the real shape is per-server overhead plus a small per-tool tail, not a flat rate you can multiply.
The other caveat is the one that could make the 50k figure true for you. Tool search isn’t unconditional. Anthropic’s docs list the cases where Claude Code loads every schema upfront instead: when ANTHROPIC_BASE_URL points at a non-first-party host, which covers most corporate proxies and gateways; when CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS is set, which ENABLE_TOOL_SEARCH can’t override; and on models older than the Claude 4.5 generation, which don’t support the tool_reference blocks it needs. If you’re behind a gateway with a large tool surface, check before you assume you’re getting deferral.
One more thing about our numbers: one of the three servers in the small test needed an OAuth flow it couldn’t run non-interactively, so it contributed nothing. We’ve counted only what connected. The token delta is the evidence here — not the session’s own account of what it could see, which is the model reporting on its own context and not something we’d bank on.
If you’re tuning an MCP setup, the practical advice in our MCP server setup guide hasn’t changed: turn off the tools you aren’t using, and prefer a server with eight sharp tools over one with thirty vague ones. Just don’t do it believing you’re clawing back 50,000 tokens.
Why does your own project config cost more than MCP servers?
Because you wrote more of it than you think. The biggest line item in our own overhead isn’t the harness or the MCP servers — it’s our project config, at 8,394 tokens.
Running from our project repo cost 38,805 tokens against the 30,411 we saw from an empty directory in the same setup. That’s 8,394 tokens, on every request, coming from two levels of CLAUDE.md, a set of project skills, hooks, and plugins.
That’s not wasted — it’s the context that makes the agent useful in this repo, and we’d rather pay it than answer the same questions every session. But it matters which side of the ledger it sits on. When someone tells you their agent’s overhead is enormous, the interesting question is how much of it they wrote themselves.
Does OpenCode really send only 7k?
On a bare install, that’s what the Systima post reported. As a comparison between the two tools, the framing doesn’t hold up.
OpenCode’s own issue tracker has a feature request from May 2026 titled “Reduce initial system prompt token overhead (~68k tokens before first user message).” The reporter’s setup: a standard agent with about 100 skills and 50-plus tools. Their breakdown blames inlined skill descriptions and tool schemas — and the issue explicitly cites Claude Code at “~10-15k tokens for the first message” as the favorable comparison.
So the same complaint, filed from the other side, produces the opposite headline. We didn’t measure OpenCode — that’s their issue tracker, not our bench — and the two setups aren’t comparable anyway: theirs is Windows with OpenCode v1.14.45 and about a hundred skills, ours is macOS. What travels is the shape, not the ratio.
The fix it was closed as a duplicate of: an MCP search tool, so schemas stay out of context until they’re needed. That is the mechanism Claude Code already ships, and it’s precisely why our MCP numbers came in at 27 tokens a tool.
What does the startup overhead cost per request?
That prefix is cached, which is why it costs about a cent and a half a turn instead of fifteen.
Anthropic prices cache reads at roughly 0.1x base input, and cache writes at 1.25x for the 5-minute TTL or 2x for the 1-hour one. Claude Code uses the 1-hour TTL — our measurements came back with the cached tokens under ephemeral_1h_input_tokens. At Opus 5’s $5 per million input tokens, the 30,411-token empty-directory prefix works out to this. We price that one rather than our own 38,805 so the figure isn’t inflated by our config; in our repo it’s about $0.019 a turn. The cache write happens once per prefix; the read is what you pay on every turn after.
| Billing state | Cost of the prefix |
|---|---|
| Cache read, every warm request | ~$0.015 |
| No caching at all | ~$0.152 |
| Cache write, 1-hour TTL | ~$0.304 |
A cent and a half a turn. The scandal deflates considerably at that price.
What doesn’t deflate is the context window. Tokens you spend on scaffolding aren’t available for the task, and on a long agentic run that’s the constraint that actually bites — earlier compaction, more lost context, shorter useful sessions. Cost and capacity are different problems, and prompt caching only solves one of them.
The other thing caching doesn’t cover: it’s a prefix match. Change your CLAUDE.md mid-session and everything after that point is re-read at full price. That’s an argument for keeping project instructions stable during a working session, not for making them shorter.
If you’re metering this against a subscription rather than the API, the plans are in our pricing tracker, and what a Claude Code subscription actually buys is its own piece — our Claude Code review works through the limits:
Should you try to cut it?
Measure before you optimize. Run the command above from an empty directory and from your project, and see which number surprises you. Most people find their own configuration is the bigger line, and that the MCP servers they were about to rip out cost a rounding error.
Then decide what you’re optimizing for — the answer changes the lever, as it does across most of our developer guides. If it’s spend, the overhead is already cached and the levers that matter are elsewhere — we went through them in eight engineering levers to cut LLM API costs, and if the problem is a team-wide bill rather than your own, spending caps is the other half of that story. If it’s context window, then trimming the tool surface and keeping project instructions tight buys you real headroom on long runs.
What’s not worth doing is switching harnesses over a number from a benchmark that measured someone else’s install. Ours is 38,805 tokens, mostly by choice, and we know exactly which 8,394 of those we wrote.
Frequently asked questions
How many tokens does Claude Code send before your prompt?
In our measurements on Claude Code v2.1.226 running Opus 5, a trivial request from an empty directory sent 29,061 tokens with MCP disabled and 30,411 with our usual user-scoped MCP servers connected. That's the system prompt, the built-in tool definitions, and the harness scaffolding. The widely-quoted 33k figure is the right order of magnitude, but your own number depends on what you've configured.
Do MCP servers add 50,000 tokens to Claude Code?
Not in a default setup. Connecting three servers with 51 tool names between them cost 1,350 tokens in our measurements. The mechanism is tool search, on by default, which loads only tool names and server instructions at session start and fetches the full schemas on demand. The cost is a fixed block per server plus a small tail per tool, not a flat per-tool rate. It does rise to something like the quoted figure when tool search is off — behind a proxy that sets ANTHROPIC_BASE_URL to a non-first-party host, with CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS set, or on a model older than the Claude 4.5 generation.
What does the startup overhead actually cost per request?
Less than the raw token count suggests, because it's cached. Anthropic prices cache reads at roughly 0.1x base input. At Opus 5's $5 per million input tokens, our 30,411-token overhead costs about $0.015 per request once warm, against $0.152 if it were re-read at full price every time. The first request that writes the cache is the expensive one: Claude Code uses the 1-hour TTL, which is billed at 2x, so writing that prefix costs about $0.30.
Does OpenCode have less overhead than Claude Code?
On a bare install, that's what the Systima post that started this reported — we didn't measure OpenCode ourselves. And the comparison that went viral put a loaded Claude Code against a minimal OpenCode. OpenCode's own issue tracker has a user reporting roughly 68,000 tokens before the first message on a standard setup with about 100 skills and 50-plus tools, and that report puts Claude Code at 10-15k for comparison. Startup overhead is mostly a property of your configuration, not of which harness you picked.