--- title: "MCP servers cost tokens before you type anything" description: "Connecting an MCP server feels free. Nothing happens until the agent calls a" canonical: https://caveman.so/news/mcp-tool-overhead-in-claude-code last-updated: 2026-09-15 --- # MCP servers cost tokens before you type anything Connecting an MCP server feels free. Nothing happens until the agent calls a tool. But the tool's schema is in the prompt from the first request, and it stays there for every request after, whether the tool is ever used or not. This is the short, practical version of a [longer field report](/news/your-agent-pays-before-it-works). It covers what we measured, how to measure your own setup in ten minutes, and what to do about it. ## What one real configuration sent We pointed a real Claude Code installation at a local capture server that imitated the Anthropic API, sent one harmless turn, and kept the request. No provider call was made. | Measure | Value | | --- | ---: | | Tool definitions on the first turn | 224,655 characters | | Tools | 91 | | Tools never called that week | 63 | | Share of schema characters from those 63 | about 69 percent | Estimated tokens, using a divisor calibrated against exact Anthropic counts on that machine, were around 35,000 for tool definitions alone. That figure is an estimate. The character count is exact. Anthropic's own documentation gives a similar scale. It describes a typical set of GitHub, Slack, Sentry, Grafana and Splunk servers at about 55,000 tokens of definitions, and notes that tool selection accuracy degrades once an agent has more than roughly 30 to 50 tools to choose from. Excess tools cost money and make the agent worse at picking the right one at the same time. ## Why it costs more than once Tool definitions render before the system prompt and the messages. They sit at the very front of the cache prefix. Two consequences: - They are resent every turn. On a stable prefix they bill at the cache read rate, about a tenth of fresh input. On an unstable one they bill in full. - A server that connects late, or a tool list that changes mid-session, invalidates the cache for everything after it, which is the whole request. ## Measure your own setup 1. Send a trivial task through your real configuration, for example "reply with DONE", against a capture sink instead of the provider. Keep every request produced during startup. 2. Redact credentials, account and session identifiers, email addresses and local paths before the capture leaves the machine. System prompts contain more personal detail than people expect. 3. Pick the request with the most tool schemas. Coding harnesses issue warmup, title and memory calls before the main turn, and the first one that contains any tool can be a tiny classifier call. 4. Split the body into system material, tool definitions, messages, and envelope. Record character counts. Keep token estimates in a separate column from anything a provider counted. Then disable one server at a time and repeat. Diff the schema characters, and check a week of invocation logs before deciding a server is dead. A large server used daily earns its place. One untouched for a month is a candidate for removal or deferral. `caveman learn` automates most of this from your local session history. It reads Claude Code, Codex, Gemini CLI and opencode logs, ranks token sinks worst-first including per-server schema weight, and runs without an account. ```bash caveman learn ``` ## Three fixes **Disconnect what you do not use.** The blunt fix, and the right one for integrations that were tried once. `claude mcp list` shows what is connected. **Defer loading.** Anthropic's API supports tool search: a few frequent tools stay loaded, the rest are marked deferred, and the model searches for and expands a definition when it needs one. The full catalog is still accepted server-side but stays out of the initial prefix. LiteLLM's proxy offers a similar pattern that replaces a large catalog with a search tool and a call tool. Recent Claude Code releases expose MCP tool search as well. Check `/context` after enabling it to see whether the tool share dropped. **Keep the list stable within a session.** Connect servers at the start, not mid-conversation. Append discoveries after the cache breakpoint rather than reordering the tool array. Make server changes at a session boundary. ## What a good result looks like Four numbers per workload, before and after: first-turn schema characters, fixed-prefix tokens as counted by the provider, cache-read share, and history growth per turn. A smaller first request is evidence. Stable task completion and correct tool selection on the same task suite decide whether the change was an improvement. ## Questions people ask ### How many tokens does an MCP server add to Claude Code? It depends on how many tools it exposes and how long their descriptions are. The one real configuration we captured sent 224,655 characters of tool definitions from 91 tools on the first turn, roughly 35,000 estimated tokens. Anthropic's documentation puts a common five-server set at about 55,000 tokens. ### Do unused MCP tools cost anything? Yes. Their schemas are in every request from the first turn. In the configuration we captured, 63 tools that were never called that week supplied about 69 percent of the schema characters. ### Does the prompt cache make this free? It makes it cheaper, at about a tenth of the fresh input rate per turn, as long as the prefix stays stable. A server that connects mid-session or a tool list that changes breaks the cache for that turn and the full cost comes back. ### What is deferred tool loading? A pattern where only a few frequently used tools are loaded into the prompt and the rest are searchable by name and description. The model fetches a full definition when it decides to use that tool. Anthropic's tool search implements it at the API level. ### Can I see this without a capture server? `/context` inside Claude Code shows how much of the window tool definitions occupy. `caveman learn` reads your local session logs and ranks servers by schema weight. A capture server is only needed for exact byte counts. ## Sources - [Your agent pays before it works](/news/your-agent-pays-before-it-works), method and full findings. - [Anthropic, tool search tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool). - [Model Context Protocol, client best practices](https://modelcontextprotocol.io/docs/develop/clients/client-best-practices). - [caveman learn](https://docs.caveman.so/docs/skill/learn).