Skip to main content
bex.co
419
Blog

MCP Tool Schemas Are Eating 72% of Your Context Window: How to Design an Infrastructure MCP Server That Doesn't

10 min readDora NodaDora Noda
Model Context Protocol
AI agents
Self-Hosting
PaaS
Engineering
Share

Connect an agent to three MCP servers — GitHub, Slack, Sentry, roughly 40 tools combined — and it burns 143,000 of a 200,000-token context window before it processes a single user message. That's 72% of the budget gone to tool schemas alone, leaving 57,000 tokens for the actual conversation: no room for a long thread, a large file, or a multi-step plan.

That number comes from a production deployment Apideck documented in 2026, and it's not an outlier — it's the default behavior of the protocol every MCP client ships today. At session start, a client fetches every tool definition from every connected server and stuffs the full JSON Schema — name, description, parameter types, constraints, examples — into the model's context before the user types anything. Connect more servers, especially ones that mirror a REST API one endpoint at a time, and the tax scales linearly with your server count, not with what the conversation actually needs.

For a platform team wiring up a handful of internal tools, that's an annoyance. For a platform whose own product is an MCP server — deploy, rollback, logs, scale, exposed so an agent can operate your infrastructure by chat — it's a design constraint you can't route around later. Get the tool surface wrong and every conversation starts by burning through a third of its budget on schemas the agent hasn't asked for yet.

Where the 72% Actually Goes​

The MCP protocol handshake is simple: on connect, a client calls tools/list against every configured server and receives back the full schema for every tool that server exposes. There's no negotiation step, no "tell me what you need." A server with 15 tools sends 15 full JSON Schema objects whether the agent will use one of them or none.

Do the math on Apideck's numbers: 40 tools across three servers averaging roughly 3,600 tokens apiece once you count the tool name, description, every parameter's type and constraints, and the enum values and examples clients often pad descriptions with to help the model pick the right tool. A 2026 arXiv survey of MCP tool description quality ("MCP Tool Descriptions Are Smelly") found this padding is itself a widespread anti-pattern — verbose descriptions added to compensate for ambiguous tool names, which then cost more tokens without actually improving tool selection accuracy.

The failure mode compounds because it's front-loaded and invisible. A developer testing a single MCP server in isolation never sees it — the bill only arrives once real users connect five, ten, or twenty servers in the same session, which is exactly the trajectory the ecosystem is on. The official registry.modelcontextprotocol.io registry passed 800 listed servers in April 2026; independent trackers estimate 13,000+ MCP servers exist in the wild once unlisted and internal deployments are counted. Every one of them is a candidate for a client to connect to, and every connection is another full schema dump at session start.

Pinterest's Fix: Domain Servers, Not One Monolith​

The clearest production counter-example is Pinterest's, documented in an April 2026 engineering writeup. Facing the same context-bloat problem internally, Pinterest didn't build one MCP server exposing every internal API. It built a fleet of domain-specific servers — one for Presto, one for Spark, one for Airflow — each owning a small, coherent set of tools scoped to what that domain actually needs, sitting behind a central registry that acts as the source of truth for which servers exist and what they're approved to do.

The results, six months in: roughly 66,000 monthly tool invocations from 844 active users, with Pinterest estimating about 7,000 engineering hours saved per month — mostly time engineers used to spend context-switching into dashboards to pull data an agent can now fetch inline. The Presto server, letting agents pull query data directly instead of opening a BI tool, is consistently the highest-traffic of the fleet. None of this required a client-side fix; it came entirely from how Pinterest scoped and organized the servers on the other end of the connection.

The registry also solved a governance problem the token-cost problem obscures: with dozens of internal servers, "which of these am I allowed to connect this agent to, and what does each one actually expose" stops being answerable by memory. A central listing with human-in-the-loop approval for sensitive operations gives both a discovery layer and an audit boundary — an agent (or a human plugging one in) checks the registry before it ever opens a connection, rather than finding out what a server can do by loading its full schema.

Three Patterns That Actually Move the Number​

Pinterest's domain-server split addresses which tools get loaded per connection. Three complementary patterns, now converging into both tooling and the protocol itself, address when they get loaded and how many exist in the first place.

Lazy loading / Tool Search. Instead of dumping every schema at connect time, a client (or a proxy in front of one) exposes a small search_tools meta-tool up front — a few hundred tokens — and fetches a tool's full definition only when the agent actually decides to call it. Focused.io's benchmark on this pattern showed initial context consumption dropping from roughly 108,000 tokens to 5,000: a 95% reduction, achieved without removing a single tool from what's available.

Claude Code implements this natively via its own ToolSearch mechanism as of mid-2026, and the pattern is significant enough that the MCP steering committee has folded a formal Tool Search capability into the protocol's second-half-2026 roadmap rather than leaving it as a client-side workaround. Community MCP gateway proxies report the same range in production — dropping initial context usage to 5-15% of the naive-load baseline by centralizing auth and injecting tool definitions on demand instead of eagerly.

Task-shaped tools, not API mirrors. The other lever is upstream of loading strategy entirely: how many tools a server exposes in the first place. The most common design mistake, called out consistently across 2026 MCP design guides, is wrapping an existing REST API one-to-one — one MCP tool per endpoint. A CRUD API with 50 endpoints becomes 50 tools, each with its own schema, none of which map to how an agent actually thinks about a task.

The fix is designing tools around what a user is trying to accomplish, not around what the API happens to expose: a handful of task-shaped tools that internally orchestrate multiple API calls, instead of a large flat list an agent has to string together itself. Design guidance converges on a middle ground — too coarse (one mega-tool with twenty parameters) confuses the model about what's actually possible; too granular (fifty micro-tools) overwhelms tool selection. The sweet spot is intent-sized: a tool per thing a user asks for, not a tool per database row operation.

Stateless protocol operation. The July 28, 2026 MCP specification release candidate drops session state from the protocol core entirely — any request can now land on any server instance, which unlocks plain round-robin load balancing and removes the Redis-session-pinning hacks 2025-era servers needed to survive behind a Kubernetes Service. That's not a context-token fix, but it's the change that makes the other two patterns viable to run at fleet scale: a registry and a lazy-loading proxy both need to scale horizontally behind a load balancer, and a stateful protocol core made that a fight.

What This Means for an MCP Server That Deploys Your App​

Here's where the design decision stops being abstract. A deploy-from-chat platform's MCP server is exactly the kind of surface that's easy to over-mirror. The naive version wraps the platform's REST API one endpoint at a time:

list_apps, get_app, deploy, list_deploys, get_deploy_status, rollback, get_logs, stream_logs, list_domains, add_domain, remove_domain, get_env_vars, set_env_var, delete_env_var, scale_service, get_metrics, list_regions, restart_service

That's a straightforward CRUD mirror, and it lands at 15-20 tools before you've added a second resource type. At Apideck's measured average of ~3,600 tokens per tool, that's 55,000-70,000 tokens gone before an agent has deployed anything, on a server whose entire job is one connection in a session where the agent is also running code, reading files, and talking to the user.

A task-shaped version collapses that to five or six tools that map to what an operator actually asks for in a sentence:

  • deploy — build + release, taking a repo ref and optional environment
  • rollback — to a specific prior release or "previous"
  • status — app health, current release, recent events, one call instead of three
  • logs — tail or range, one tool handling both the live-stream and historical case
  • configure — env vars, domains, and scaling as one parameterized surface instead of six separate CRUD tools per resource type

That's the same operational coverage at roughly a third of the token cost, and it maps to how someone actually phrases a request in chat — "roll this back to yesterday's release," not "call get_deploy_status, then get_deploy_history, then rollback with deploy_id=X."

Lazy loading matters here specifically because a platform's MCP surface doesn't stay at five tools forever — add preview environments, database provisioning hooks, and per-team RBAC, and the naive count creeps back up. Exposing a search-first surface instead of a flat list means the token cost of the server stays roughly constant as its feature surface grows, instead of scaling linearly with every tool a product team ships. And a registry — even an internal one listing "this MCP endpoint deploys git repos and rolls back releases, scoped to these environments" — is the same governance boundary Pinterest built for internal tools, applied to an external one: an agent, or the human wiring an agent to a new environment, can find out what a deploy server can actually do without opening a connection and eating the schema cost to find out.

The Number That Actually Matters​

The 72% figure is really a warning about what happens when you let architecture happen to your MCP server instead of designing it: connect enough naively-mirrored servers, or ship enough naively-mirrored tools yourself, and the protocol will spend most of an agent's attention on descriptions of things it hasn't decided to do yet. The fix isn't a client-side patch — it's the same three decisions Pinterest and the MCP spec authors converged on independently: scope servers to a domain instead of a monolith, shape tools around tasks instead of endpoints, and load schemas on demand instead of all at once. For a platform whose product is "an agent can operate your infrastructure through this one connection," that's not an optimization pass to defer — it's the first design review the server needs before it ships.

Bex.co is the open-source, AI-native Render alternative — push a git repo, get a running HTTPS service on machines you own, with deploy, rollback, and logs exposed as first-class MCP tools designed around what an agent actually asks for, not a mirror of the REST API underneath. Star the repo on GitHub or deploy your first app today.

Sources​

Related articles

Give your agents a chain backend

Autonomous agents hit RPC endpoints very differently than people do. See what bex router handles on their behalf.

Read the agents guide
Back to all posts