Tool search did not retire MCP pruning

Tool search defers MCP tool definitions by default, so unused servers no longer cost you full schemas on every turn — but the docs still tell you to disable servers you are not using, because tool names and server instructions load every session regardless.

You have six MCP servers configured, /context says you are further into the window than you would like, and a cost guide tells you to disconnect the ones you are not using because their schemas ride along on every request. Before you spend the afternoon pruning, know that the mechanism the guide describes is no longer how Claude Code loads MCP tools by default — and that the official docs still tell you to disable unused servers anyway, in the same paragraph where they explain the deferral.

Both halves are true. They are just about different costs.

What deferral actually changed

Tool search is on by default. The docs are unambiguous about what that means for context:

Tool search keeps MCP context usage low by deferring tool definitions until Claude needs them. Only tool names and server instructions load at session start, so adding more MCP servers has minimal impact on your context window.

There is also no fixed per-server tool cap — the docs say the practical limit is your context budget. So the old mental model, "every server's full JSON schemas sit in the system prompt on every turn," describes the ENABLE_TOOL_SEARCH=false world, not the default one.

What it did not change

The Reduce MCP server overhead section of the costs page states the deferral and then, two bullets later, still says:

Disable unused servers: Run /mcp to see configured servers and disable any you're not actively using.

The MCP quickstart says the same thing about removing a server you are done with: each connected server takes some space because its tool names and server instructions load into every session. Deferral shrank the per-server residue from full schemas to names plus instructions. It did not take it to zero — and server instructions are a real block, truncated at 2KB each, one per server.

Lever	What it removes from context	What else it costs you
Leave a server connected (deferred)	nothing — names + server instructions stay	a `ToolSearch` round trip the first time Claude wants a tool
Disable an unused server	its names and instructions	you have to re-enable it before it can be used
Prefer a CLI (`gh`, `aws`, `gcloud`, `sentry-cli`)	the whole per-tool listing	Claude has to learn the CLI's flags, and you need it installed and authenticated
`alwaysLoad: true` on a server	nothing — it adds full schemas upfront	worth it only for tools needed on nearly every turn

The CLI half of the advice is the part that survived intact: the docs still recommend CLI tools over MCP servers precisely because they add no per-tool listing at all.

Where the old advice is still fully live

Deferral is not universal. In these configurations Claude Code loads every MCP tool definition upfront, and pruning buys back exactly what the old guides claimed:

ANTHROPIC_BASE_URL pointing at a non-first-party host (most proxies do not forward tool_reference blocks), unless you set ENABLE_TOOL_SEARCH=true and your proxy really does support them
ENABLE_TOOL_SEARCH=false
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS set — this one wins even if you set ENABLE_TOOL_SEARCH yourself
Microsoft Foundry deployments hosted on Azure, which reject tool search server-side
Google Cloud Agent Platform models earlier than the Claude 4.5 generation
Any server or individual tool marked alwaysLoad
ENABLE_TOOL_SEARCH=auto, where definitions load upfront until they cross 10% of the window (auto:N for a custom threshold)

Do this instead of guessing

Run /context before you prune anything. It shows the MCP row separately from skills, plugins, memory files and CLAUDE.md, and the docs point you at it in exactly this situation. Prune the largest row, not the one a blog post named.

bash

# what is configured, and what is connected
claude mcp list

# then, inside a session
/context

What is unverified here

Nobody has measured this. The mechanism is quoted from the docs, but the interesting quantity — how many tokens a connected-but-idle server actually costs you in a real config — is not in the docs and is not in this tip. The reported comparison to make:

Start a session with your usual servers and run /context; note the MCP row.
Restart with ENABLE_TOOL_SEARCH=false claude and run /context again.
Disable one server with /mcp and re-run /context in the default configuration.

Step 2 tells you how much deferral is saving you. Step 3 tells you what pruning still buys on top of it. Until someone posts those three numbers for a realistic server set, treat "pruning is obsolete" as an overcorrection of a claim that was itself out of date.

Checkpoint

In the default configuration, what still enters context for a connected MCP server you never use?
Show answerAnswer
Its tool names and its server instructions — not its full tool definitions, which tool search defers until Claude needs them. So the widely repeated claim that every server's JSON schemas ride in the system prompt on every turn describes the ENABLE_TOOL_SEARCH=false world, not the default one. The correction cuts both ways, though: the residue is not zero, server instructions are a real block truncated at 2KB each with one per server, and the Reduce MCP server overhead section of the official costs page states the deferral and then still says Disable unused servers two bullets later — as does the MCP quickstart about a server you are done with. Tokens are also not the only cost: a connected server's tools stay callable, and one that fetches external content stays a prompt-injection surface the MCP docs tell you to vet.
Name two configurations where MCP tool definitions load upfront regardless of the default.
Show answerAnswer
Any two of: ENABLE_TOOL_SEARCH=false; CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS set, which wins even if you set ENABLE_TOOL_SEARCH yourself; ANTHROPIC_BASE_URL pointing at a non-first-party host, since most proxies do not forward tool_reference blocks; Microsoft Foundry deployments on Azure, which reject tool search server-side; Google Cloud Agent Platform models earlier than the Claude 4.5 generation; any server or individual tool marked alwaysLoad; or ENABLE_TOOL_SEARCH=auto, where definitions load upfront until they cross 10% of the window. In every one of these the old pruning advice is not merely still useful — it buys back exactly what the old guides claimed, which makes those guides out of scope rather than simply wrong. Behind a corporate gateway, assume you are in that upfront-loading world until you have checked.
Which command tells you whether MCP is actually your largest context consumer?
Show answerAnswer
/context. It shows the MCP row separately from skills, plugins, memory files and CLAUDE.md, and the docs point you at it in exactly this situation — prune the largest row, not the one a blog post named. claude mcp list complements it from outside the session by showing what is configured versus what is actually connected. The numbers themselves are yours to measure, because nobody has published them for a realistic server set: run /context as usual, again under ENABLE_TOOL_SEARCH=false claude to see what deferral is saving you, then again after disabling one server with /mcp to see what pruning still buys on top.