Your MCP Servers Are Eating Your Agent's Context

Every MCP server you connect promises your agent more reach. What it does not advertise is the bill. Tool names, descriptions and JSON schemas all travel inside your agent’s context, and in many setups they travel on every request, before you have typed a word. One r/mcp post estimates that a setup of 15 or more servers, each exposing 20 to 30 tools, can burn 60,000 tokens per request loading tool schemas. That is context your agent cannot spend on your code, your docs or its own reasoning, and it gets worse at choosing tools as the list grows.

This is a playbook, not a lament. You will learn how to estimate your overhead in two minutes, how to check the real number, how to group and trim servers, how to design MCP tools the model picks correctly, and when lazy loading or code execution makes the problem smaller.

Why tool definitions cost you on every request

A tool definition is prompt text. The client hands the model a name, a description and an input schema for every tool it exposes, so the model knows what it can call. If your client loads all of them upfront, they sit in the context window on every turn, whether the agent touches them or not.

Anthropic put numbers on this in its post on advanced tool use. A five-server setup of GitHub, Slack, Sentry, Grafana and Splunk came to 58 tools and roughly 55K tokens “before the conversation even starts.” The same post says Anthropic has seen tool definitions consume 134K tokens internally before optimization.

Token cost is only half of it. That post also names the most common failures: wrong tool selection and incorrect parameters, especially when tools have similar names. Anthropic’s guide to writing tools for agents is blunter: “More tools don’t always lead to better outcomes,” and too many or overlapping tools “can also distract agents from pursuing efficient strategies.”

So every idle tool costs you twice. It takes space, and it adds one more wrong answer to the multiple-choice question your agent answers at every step.

Run the back-of-envelope audit

The first r/mcp post offers a quick formula: number of MCP servers × average tools per server × 150 tokens per tool definition = baseline context cost per request. The author’s rule of thumb is that anything over 30,000 tokens means you are paying for tools your agent rarely uses.

Worked example. Say you run 12 servers averaging 20 tools each. That is 240 tools. At 150 tokens apiece you carry 36,000 tokens of schemas before the first message. On a 200K-token window, 18% of your agent’s working memory is gone to a menu.

Now the skeptical part. Treat 150 tokens as a floor, not an average. In Anthropic’s five-server example, 58 tools cost about 55K tokens, which works out to roughly 950 tokens per tool. Slack’s 11 tools alone came to about 21K. Rich schemas with nested objects, enums and long descriptions cost far more than the formula assumes.

So use the formula to decide whether to look, then actually look. In Claude Code, the /context command visualizes what is filling the window and, per the docs, shows optimization suggestions for context-heavy tools. The /mcp panel shows the tool count next to each connected server. Sort by that count and you will usually find two or three servers carrying most of the weight. (On Claude Code defaults most schemas are already deferred, as covered below, so the formula bites hardest on clients that load everything upfront.)

Group servers by job, not by vendor

The default way an MCP setup grows is one server per service. You add GitHub, then GitLab, then Buildkite, then Slack, and each arrives with its own pile of tools, many of them near-duplicates (search, list, get, create) that differ only by vendor.

The first r/mcp post argues that grouping servers works better than running one per service, and suggests buckets by job:

• Code and CI: GitHub, GitLab, Buildkite
• Comms: Slack, Discord, email
• Data: Postgres, Redis, BigQuery
• Product tracking: Jira, Notion, Linear

Why this helps: a grouped server can expose one search and one create per job, with the vendor as a parameter, instead of four vendors’ worth of overlapping verbs. It also fits Anthropic’s advice on namespacing, grouping related tools under common prefixes by service or by resource (asana_search, jira_search) so the agent can tell them apart. Anthropic notes that prefix versus suffix naming had “non-trivial effects” on its evaluations and that the effect varies by model, so test your own.

Grouping also makes the on and off decision obvious. You rarely need data tools while fixing CSS. In Claude Code you can toggle a server off in /mcp without losing its configuration, and the choice is remembered per project. Keep the job groups you use weekly and switch off the rest.

Collapse CRUD tools into fewer, broader actions

If you build MCP servers, the classic mistake is mirroring your REST API. The second r/mcp post describes exactly that: get_user_by_id, get_user_by_email, search_users, update_user_status and so on. Its author says that past roughly 15 to 20 granular tools the schemas clutter the system prompt, the model gets indecisive, hallucinates calls or picks the wrong one, and latency goes up.

What worked for them was collapsing tools into broader actions with enum parameters, along these lines:

• query_user(filter_by: 'id' | 'email', value)
• manage_user(action: 'search' | 'update', ...)

The choice moves from “which of these similar names” to “which value of a documented enum,” and that is a much easier question for a model.

Anthropic’s guidance lands in the same place. It calls tools that “merely wrap existing software functionality or API endpoints” a common error, and suggests consolidating steps the agent would chain anyway: a schedule_event tool instead of list_users, list_events and create_event, or one get_customer_context tool instead of separate lookups for the customer, their transactions and their notes.

One caution. Do not collapse everything into a single do_anything(action, payload) tool. You have just moved the confusion into one giant schema. Group by resource or workflow, keep each tool’s purpose describable in one sentence, and stop there.

Write descriptions that say when not to call

Tool descriptions are not API docs. They are prompt text the model reads to decide what to do, and the second r/mcp author’s advice is to treat them like prompt engineering, not Swagger. Their most striking claim: telling the model explicitly when not to call a tool cut bad invocations in half for them. That is one team’s number, but it costs you ten minutes to test on your own server.

A useful description answers three questions: what it does, when to use it, and when to use something else. For example: “Search users by name or email. Use this before update_user when you do not have an ID. Do not use it to list all users; it returns at most 20 matches.”

Anthropic’s guide says to write descriptions as if you were explaining the tool to a new hire, making implicit context explicit (query formats, niche terminology, how resources relate) and naming parameters unambiguously: user_id instead of user. It also reports that precise refinements to tool descriptions helped Claude Sonnet 3.5 reach state-of-the-art performance on SWE-bench Verified. Descriptions are not decoration.

Two practical limits. Claude Code truncates tool descriptions and server instructions at 2KB each, so put the critical guidance near the start. And every word you add is context you pay for whenever the tool is loaded, so be precise rather than long.

Let the agent load tools lazily, or write code instead

The biggest cut is not loading schemas until they are needed.

If you use Claude Code, this is already the default. Its MCP docs say tool search defers tool definitions: only tool names and server instructions load at session start, and full schemas are fetched on demand. ENABLE_TOOL_SEARCH controls it. auto loads definitions upfront while they total under 10% of the context window, auto:N sets your own percentage, and false loads everything upfront. Setting alwaysLoad: true on a server pins its tools for every turn. Deferral falls back to upfront loading in some setups (a non-first-party ANTHROPIC_BASE_URL, for one), so check /context rather than assuming.

For server authors, deferral changes what matters. Your server instructions now help Claude decide when to search for your tools at all, so say what category of task you handle and when to reach for you. On the API side, Anthropic reports its Tool Search Tool took Opus 4 from 49% to 74% accuracy on internal MCP evaluations with large tool libraries, and Opus 4.5 from 79.5% to 88.1%.

Code execution goes further. In Code execution with MCP, Anthropic presents tools as files the agent browses and calls from code, which also keeps bulky intermediate results out of context. In its worked example (a Google Drive transcript attached to a Salesforce record), token usage fell from 150,000 to 2,000, a 98.7% saving. That is one illustrative workflow, not a benchmark, and the post warns that running agent-generated code needs sandboxing, resource limits and monitoring.

When MCP is still worth the overhead

None of this means MCP is bad. It means every server should earn its place.

The first r/mcp post mentions a developer who deleted every MCP server in his setup and got 40% of his context window back. That is a real trade, but for most setups it is an overcorrection. The better question, server by server, is whether it gives your agent something it cannot get more cheaply.

Often the cheaper path is a CLI. Claude Code’s own cost guidance says tools like gh, aws, gcloud and sentry-cli are more context-efficient than MCP servers because they add no per-tool listing, and Claude can run them directly. The Reddit author makes a similar call about local tools that get called frequently: the overhead is not justified. If your agent has a shell and the service has a good CLI, you may not need the server.

MCP earns its keep when:

• The service has no decent CLI, or you want scoped access you would rather not hand to a shell.
• The tool returns structured data the agent chains into its next call.
• You want one integration that works across several clients.
• The server is well designed: few tools, clear descriptions, bounded responses.

Watch response size too. Claude Code warns when an MCP tool’s output exceeds 10,000 tokens and limits it to 25,000 by default (MAX_MCP_OUTPUT_TOKENS raises it). Anthropic’s tool guide recommends pagination, filtering and truncation with sensible defaults, so a single call cannot flood the window.

Practical takeaways

• Run the formula (servers × tools × 150 tokens) for a rough floor, then check the real number with /context.
• Treat 150 tokens per tool as optimistic. Anthropic’s five-server example averages closer to 950.
• Switch off servers you have not used this week in /mcp. You keep the config and lose the weight.
• Group servers by job (code and CI, comms, data, product tracking), not one per vendor.
• If you build servers, stop mirroring REST endpoints. Collapse lookups into one tool with an enum filter.
• Give every description a “use this when” line and a “do not use this when” line, and keep the key guidance in the first few sentences.
• Name parameters unambiguously (user_id, not user) and namespace tools by service or resource.
• Leave tool search on in Claude Code unless you have a reason not to, and pin only the handful of tools you need every turn.
• Prefer a CLI when one exists and your agent already has a shell.
• Bound tool responses with pagination and sensible defaults.

Spend context on the work, not the menu

Context is the working memory your agent thinks with. Every schema you load by default is a small tax on that memory and a small bump in the odds of a wrong call. Measure what you carry, cut what you do not use, and design the tools you keep so the right choice is the obvious one. Your agent gets cheaper, faster and, more to the point, better at the actual job.

Want more playbooks like this? Subscribe to the HelloBuilder newsletter.