How to Make MCP Servers Not Take Up as Much Context in Claude Code: Tool Search, alwaysLoad, Scopes and Output Caps

Add a GitHub server, a database server, a browser server and the company's internal one, and a fresh Claude Code session can be tens of thousands of tokens into its context window before you type a word. Every tool a server exposes has a name, a description and a JSON schema, and all of it used to be sent to the model on every turn. "How do I make MCP servers not take up as much context in Claude Code?" is a question people ask this site often enough that it deserves a straight answer. The good news is that the biggest fix is now on by default. The rest of this post covers what that fix does, how to check it is working, and the five other levers you have.

Start by measuring: /context

Before changing anything, run /context in a session. It shows a breakdown of what is occupying the window: system prompt, tools, memory files, messages. If MCP tools are a large slice, the levers below will help; if the slice is CLAUDE.md and auto memory, the fix is different and is covered in the context management post. /mcp shows every connected server with its connection status and tool count, which tells you which servers are the heavy ones.

Lever 1: tool search (on by default)

Claude Code no longer sends every MCP tool definition up front. With tool search enabled, only the tool names and each server's instructions are loaded at session start; the full definitions are deferred. When Claude needs a tool it has not loaded, it calls a built-in ToolSearch tool to fetch the definitions it wants, and only those enter the context. The documentation's summary is that adding more MCP servers has "minimal impact on your context window", and that there is no fixed per-server tool cap; the practical limit is the window itself.

You can see it working: in a session with several servers connected, the first time Claude uses a server's tool there is a short ToolSearch step before the real call. That step is the deferred definitions being loaded. Tools loaded this way are allowed a longer description (16,384 characters) than tools loaded up front (4,096), because the description is only paid for when it is actually fetched.

Tool search is enabled by default, but there are cases where it is off, and that is the first thing to check if your context is still heavy:

• A custom ANTHROPIC_BASE_URL. When the base URL points at a non-first-party host, Claude Code disables tool search, because most proxies do not forward the tool_reference blocks it relies on. If your gateway does forward them, set ENABLE_TOOL_SEARCH=true explicitly to override that fallback.
• CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS. Set this (usually to make a strict gateway accept requests) and tool search stays off; ENABLE_TOOL_SEARCH cannot override it. From v2.1.227 an organisation can keep tool search on under that variable through managed settings.
• Hosted deployments that reject it. Microsoft Foundry deployments on Azure reject tool search server-side, and Claude Code falls back to loading MCP tools up front there. HIPAA-configured sessions also run with it off.

Without tool search, Claude Code sends every tool definition at the start and uses a WaitForMcpServers tool instead of ToolSearch for servers still connecting. If you are in one of those environments, the remaining levers matter much more.

Lever 2: alwaysLoad, in both directions

Deferral has a cost: the first use of a tool costs an extra round trip, and Claude can only choose a deferred tool if the name and server instructions are enough to make it search. For a server whose tools you use on every turn, you may prefer the old behaviour. The alwaysLoad field on a server's configuration entry loads that server's tools up front; a server author can do the same per tool by setting "anthropic/alwaysLoad": true in that tool's _meta. The reverse works too: a tool marked "anthropic/alwaysLoad": false stays deferred even when your configuration sets the server to load up front (for servers passed with --mcp-config, from the Agent SDK or from a plugin; v2.1.285 or later).

The context rule of thumb: leave everything deferred, then mark up front only the two or three tools that every session uses in its first turn. Marking a whole twelve-tool server alwaysLoad puts all twelve definitions back into the window permanently.

Lever 3: disable servers per project

The cheapest context is a server that is not connected. Run /mcp, select a server and turn it off. The choice is saved per project in ~/.claude.json, in a disabledMcpServers list (an opt-out list for most servers, including plugin servers and claude.ai connectors), and the server shows as "Disabled for this project (re-enable via /mcp)" until you flip it back. Built-in servers that default to off, such as computer-use, live in the matching enabledMcpServers opt-in list.

Project .mcp.json servers that a teammate checked in have their own approval settings, enabledMcpjsonServers and disabledMcpjsonServers, in the settings file; an entry in the disabled list blocks that server in every permission mode. In -p and SDK runs, project servers load without a prompt, so there the disabled list or --strict-mcp-config is how you keep one out. claude mcp reset-project-choices clears the approvals if you want to start again.

Lever 4: pick the right scope so servers only load where needed

A server added with --scope user is available in every project, which also means it loads (at least its tool names) in every project. --scope local (the default) keeps it to the current project path; --scope project writes it to .mcp.json for the team. When the same server name is defined at more than one scope, local wins over project, project over user, user over plugin, and plugin over a claude.ai connector, and the whole winning entry is used rather than a merge. A quick audit: claude mcp list shows everything configured with its health; anything at user scope that only one project needs is a candidate to move. The MCP servers guide goes into the scopes in more detail.

Lever 5: cap what tool results put into the window

Tool definitions are the fixed cost; tool results are the variable one, and a single schema dump or file listing can be larger than every definition combined. Claude Code caps MCP tool output at 25,000 tokens by default (MAX_MCP_OUTPUT_TOKENS changes it) and warns when a result passes 10,000. Separately, successful text results over 50,000 characters are written to a file in the session's tool-results directory and replaced in the conversation with a reference, so Claude reads what it needs instead of swallowing the whole thing; a server author can raise that threshold for one tool with anthropic/maxResultSizeChars, up to 500,000. If your context fills up mid-session rather than at the start, this is the lever, together with asking for narrower queries.

Lever 6: shorter descriptions, better server instructions

If you maintain the server, write server instructions that say what category of tasks the tools handle and when Claude should search for them, and keep them short; with tool search on, those instructions are the main thing Claude sees about your server, so they do the job that the tool descriptions used to do. Claude Code truncates server instructions and up-front tool descriptions at 4,096 characters and deferred descriptions at 16,384, and reads only the part before the cut when matching a search, so put the words Claude would search for near the start. CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH (v2.1.280+) replaces both limits with a number you choose, in either direction.

A practical order of operations

1. /context to see whether tools are actually the problem.
2. Confirm tool search is on: no custom base URL, no CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS, or ENABLE_TOOL_SEARCH=true set deliberately.
3. /mcp and disable the servers this project does not use.
4. Move single-project servers from user scope to local or project scope.
5. Leave everything deferred except the handful of tools used on turn one.
6. Watch for oversized results; lower MAX_MCP_OUTPUT_TOKENS or ask for narrower calls if they recur.

Do that once per project and MCP stops being the thing that eats your window. The sessions get longer before compaction, and compaction is where the expensive mistakes happen. If you run those long sessions with several servers and step away while they work, the one thing the context window cannot do is tell you when the run is finished.