Every MCP tool comes with a definition: a name, a description and a parameter schema. Tool search is how Claude Code keeps those definitions out of the context window until the model actually needs one. With it, connecting ten servers costs almost nothing up front; what costs context is the results the tools return.
How it works
At session start, only the names of MCP tools and each server’s instructions (a short text the server provides about when to use it) go into the context. When Claude decides it needs a tool, it calls the built-in ToolSearch tool, which loads that tool’s full definition. Only then can Claude call it.
Because nothing beyond the names is loaded, adding servers has little effect on the context. Claude Code sets no fixed cap on tools per server; the practical limit is your context budget.
How it was before
Without tool search, Claude Code loads every tool definition from every connected server at session start, and they stay in the context for the whole session. Every connected server took up room on every request, even one you never used in that session.
Claude Code 2.1.7 (January 2026) turned on an automatic mode for everyone: once MCP tool definitions passed 10% of the context window, they were deferred behind search instead of loaded upfront. Today the default goes further and defers all MCP tools.
When tools still load upfront
- Configured that way.
ENABLE_TOOL_SEARCH=falseloads everything upfront.autobrings back the threshold mode (load upfront while the definitions stay under 10% of the context), andauto:Nsets your own percentage. - A server marked
alwaysLoad. Setting"alwaysLoad": trueon a server in the MCP config loads its tools upfront regardless ofENABLE_TOOL_SEARCH. Use it only for a few tools Claude needs on every turn, since each one takes context all session. It also makes startup wait for that server, up to the 5-second connect timeout. - Fallbacks. Claude Code turns tool search off when
ANTHROPIC_BASE_URLpoints at a non-first-party host, since most proxies cannot pass the needed blocks through (setENABLE_TOOL_SEARCHto override), on models earlier than Claude Opus 4 and Sonnet 4, and on Microsoft Foundry deployments hosted on Azure.
A tool that loads upfront has a shorter description limit: 4,096 characters, the same as server instructions. A description loaded through tool search is cut at 16,384 characters.
What still costs context: tool results
A tool result goes into the conversation and is sent again with every later request, like any other message. Claude Code limits it:
- Above 10,000 tokens it shows a warning.
- The default limit is 25,000 tokens. Change it with the
MAX_MCP_OUTPUT_TOKENSenvironment variable. - A successful text result over the limit, or longer than 50,000 characters, is saved to a file, and the conversation gets a short message with the file path instead. Claude reads the file when it needs the content.
So one browser snapshot or a large query result can cost more than every tool definition you have. /usage shows each MCP server’s share of your usage, and /context shows what is in the context right now.
Gotchas
- Upfront tools and the cache. Connecting or removing a server mid-session breaks the prompt cache when its tools load upfront. Deferred tools do not.
- Disabling still helps. The costs guide still recommends turning off servers you do not use in
/mcp, and preferring a CLI such asghorawswhen one exists, since a CLI adds no tool listing at all.
Related
- MCP: what servers and tools are.
- MCP in Claude Code: adding and managing servers.
- Context window: what else is in the context at session start.
- Reducing token usage: other habits that keep the context small.