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 traditional behaviour is eager, and many agents still work that way: 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's README documents around 82 tools across 20 toolsets, five of them enabled by default. GitHub has never published a token cost for that manifest, and the third-party estimates in circulation disagree badly — 42,000, 55,000 and 64,600 tokens all appear in blog posts and issue threads about the same server — so treat any single figure with suspicion. What is not in dispute is the direction: a server that size is a large block of text the model mostly ignores, paid before you've typed a word. Connect two or three like it and the overhead adds up fast.

Now multiply by turns and by price. Take an illustrative 40,000-token manifest — a round number, not a measurement. With Claude Opus 5.5 at $4 per million input tokens (Anthropic pricing, as of October 2026), that's $0.16 of input — once. But if it rides along on 150 turns in a session, that's $24 of input just for the privilege of having a tool connected that you may never call. Prompt caching helps a lot here: cache hits on Opus 5.5 bill at $0.20 per million (5% of input), which drops that to about $1.20 — 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 5.5 ($2 / $10 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.

Does Claude Code already load MCP tools lazily?

Yes, by default, since it shipped MCP tool search — and that is the biggest change to this topic since we first wrote about it. As of October 2026, Claude Code's MCP docs say tool search is on by default for Claude Opus 4.5, Sonnet 4.5, Haiku 4.5 and later: MCP tool definitions are deferred, only tool names and server instructions enter context, and Claude loads a tool's full schema through a search step when it needs it. The same mechanism exists on the API as the tool search tool, where you mark tools defer_loading: true.

It is not universal, and the exceptions are exactly where people get caught:

Third-party proxies. When ANTHROPIC_BASE_URL points to a non-first-party host, Claude Code turns tool search off, because most proxies don't forward the blocks it relies on. Every schema loads upfront again unless you set ENABLE_TOOL_SEARCH explicitly and your proxy supports it.
alwaysLoad servers. A server (or a single tool) marked alwaysLoad: true loads in full at session start, whatever the setting.
Some hosted deployments. Microsoft Foundry on Azure and Agent Platform models older than the Claude 4.5 generation load all MCP tools upfront.
Threshold mode. ENABLE_TOOL_SEARCH=auto keeps tools upfront while their definitions total under 10% of the context window, and defers them past that; auto:N sets your own percentage.

Deferral also isn't zero. Every connected tool still contributes its name, and each server its instructions, on every turn. Anthropic's own cost guide still recommends disabling unused servers with /mcp and preferring CLIs like gh or aws, which add no per-tool listing at all. Run /context to see what your servers actually occupy. Other agents vary: check whether yours defers tool schemas before assuming it does.

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 — which matters most in agents that don't defer tool schemas natively, or in Claude Code setups where tool search is off. 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 10% of input on Sonnet 5.5 (5% on Opus 5.5, 2.5% on Fable 5.1), 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: