Lazy MCP Loading: Stop Paying for Idle Tools

What is lazy MCP loading?

Lazy MCP loading is deferring an MCP server's tool manifest — every tool name, description, and parameter schema — until the moment the agent actually wants to call one of its tools, instead of injecting the whole manifest into the context window on every single turn. The default behaviour is eager: the instant you connect a server, its full manifest rides along with every message you send, whether you touch those tools or not. Lazy loading flips that. The agent sees a thin index up front and pulls the full schema for a tool only when it decides to use it. I spend most of my day inside Claude Code with a handful of servers connected, and the thing that bothered me — once I started actually counting tokens — was how much I was paying for tools that just sat there. You connect GitHub because you review PRs twice a week, and then you pay for its manifest on every prompt, including the three hundred where you're just editing a function. That's the problem lazy loading exists to solve. This is a spoke off the broader question of how to reduce AI coding agent token usage. If you want the full menu of levers, start there. This piece is about one lever, done properly.

Why does eager MCP loading cost so much?

Eager loading costs so much because the manifest is fixed overhead paid on every turn, and turns add up fast. A coding session isn't one big request — it's dozens or hundreds of round-trips as the agent reads files, runs commands, and reacts to output. Every one of those round-trips re-sends the system prompt and the full tool manifest for each connected server. Here's the part that surprises people: the manifest for a big server can be large. The GitHub MCP server ships on the order of 90-plus tools, and measurements of its manifest put it at roughly 50,000 tokens — about a quarter of Claude's 200K context window, paid before you've typed a word. Connect two or three servers like that and you've spent a meaningful slice of your window on text the model mostly ignores. Now multiply by turns and by price. With Claude Opus 4.8 at $5 per million input tokens, 50,000 tokens of manifest is $0.25 of input — once. But if it rides along on 150 turns in a session, that's $37.50 of input just for the privilege of having a tool connected that you may never call. Prompt caching helps a lot here, because cache reads run at roughly 10% of the input price, dropping that to a few dollars — but caching only works while the prefix is stable and the cache is warm, and a manifest you never use is still tokens you never needed to send. On Sonnet 4.6 ($3 / $15 per MTok) or Haiku 4.5 ($1 / $5) the absolute numbers shrink, but the ratio doesn't: you're paying continuously for capability you use intermittently. The numbers behind this are collected in our AI coding agent token costs breakdown.

How does lazy loading actually work?

Lazy loading works by splitting the manifest into a cheap index and an expensive body, and only sending the body on demand. The mechanics are simple once you see them:

At connect time, the agent receives a minimal descriptor per server — enough to know the server exists and roughly what it covers — rather than the full schema for all its tools.
When the model decides it needs a tool, the loader resolves the full schema for that specific tool (or that tool's group) and injects it for the turns where it's relevant.
When the work is done, the schema can drop back out of the active context, so it isn't re-sent on the next two hundred unrelated turns.

The result is that the per-turn floor — the cost you pay before you've said anything useful — collapses toward zero for servers you aren't currently using. You keep the capability; you stop pre-paying for it. This is the same family of move as output filtering (compacting noisy tool results before they hit context) and semantic code search (retrieving the right code by meaning instead of dumping whole files) — different lever, same principle: only the bytes that earn their place should reach the model. It pairs naturally with prompt caching rather than competing with it. Caching makes the bytes you do send cheaper to re-send; lazy loading makes sure you weren't going to send most of them in the first place. Stack both and the savings compound.

How to apply lazy MCP loading today

You can get most of the benefit today with a mix of discipline and tooling. In rough order of effort:

Audit what's connected. List your active MCP servers and, for each, ask honestly: do I call this on most sessions, or once a week? The manifest cost is paid daily regardless of frequency. Our best MCP servers for Claude Code ranking scores each common server on exactly this — token cost, not just usefulness.
Prune ruthlessly. The cheapest token is the one you never send. A server you use weekly is usually better connected on demand than left on permanently. This is the manual version of lazy loading, and it's free.
Keep only one or two always-on servers. Pick the ones that fire on most turns. Everything else is a candidate for lazy treatment.
Let a layer do it automatically. Manual pruning is real work and you'll get it wrong. This is where Tokenade comes in: it sits between your agent and its servers and loads tool manifests lazily — the full schema is fetched only when the agent reaches for that tool — so a four- or five-server setup costs roughly what a one-server setup did. It does the same for noisy output (it compacts before context) and codebase reads (semantic search instead of whole-file dumps), and shows you the savings on a dashboard so you can see the per-turn floor actually drop.

A quick gut-check before you commit to anything: run a normal session and look at how many input tokens land before your first real instruction. If a big chunk of that is tool manifests you didn't touch, lazy loading is free money. You can sanity-check rough numbers with the token counter and the LLM token cost calculator.

What goes wrong (anti-patterns)

The failure modes here are mostly about confusing "connected" with "free." A few to watch for:

Hoarding servers. Connecting every interesting MCP server "just in case" is the single most expensive habit. Each one adds fixed per-turn overhead whether it fires or not. If you wouldn't pay a monthly subscription for a tool you use once a fortnight, don't pay a per-turn tax for it either.
Assuming caching makes it free. Prompt caching cuts re-send cost to roughly 10% of input, which is excellent — but it doesn't help on a cold cache, doesn't survive a manifest change, and never beats simply not sending the bytes. Caching is a discount on a bill you can mostly avoid.
Lazy loading the wrong tools. If a tool genuinely fires on most turns, deferring it just adds a round-trip to resolve the schema each time. Lazy loading is for the long tail — the servers you reach for occasionally — not the one or two you live in.
Eyeballing instead of measuring. "It feels lighter" is not a number. Track the per-turn input floor before and after, on a real workload. If you can't see the savings, you can't tune them.

The honest summary: most of us connected too many MCP servers, never counted what they cost, and let prompt caching paper over the bill. Lazy loading is the structural fix — pay for tools when you use them, not when you connect them. It's a smaller idea than context engineering as a whole, but it's one of the highest-leverage pieces of it, and unlike most of that discipline it's something a tool can just do for you.

See also: