Configure the MCP description length cap
CHANGELOG · original
Added CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH to change the 2,048-character cap on MCP tool descriptions and server instructions for every MCP server in the session Open official changelog ↗ Documentation
Documentation excerpt
Tool search for MCP server authors
If you're building an MCP server, the server instructions field becomes more useful with tool search enabled. Server instructions help Claude understand when to search for your tools, similar to how skills work.
Add clear, descriptive server instructions that explain:
- What category of tasks your tools handle
- When Claude should search for your tools
- Key capabilities your server provides
Claude Code cuts a tool description or server instructions that run past these default limits, and Claude sees only the text before the cut:
- Server instructions, and the description of a tool that loads upfront: 4,096 characters
- The description of a tool that Claude loads through tool search: 16,384 characters
Keep descriptions and instructions concise, and put critical details near the start. When tool search matches Claude's query against a tool's description, it reads only the part within the shorter limit, so put the words Claude would search for near the start too. A tool loads upfront and keeps the shorter limit whenever it isn't deferred, for example when tool search is off, when the tool is marked to load upfront, or when its server is exempt from deferral.
Before v2.1.296, the shorter limit was 2,048 characters, and before v2.1.295 it applied to every tool description, including one loaded through tool search.
Change the description length limits
To change the default limits of 4,096 and 16,384 characters for the MCP servers in your session, set CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH to a number of characters. Claude Code uses that number for both limits. With 8192, for example, you raise the 4,096-character limit on server instructions and tool descriptions loaded upfront, and lower the 16,384-character limit on tool descriptions loaded through tool search. This variable requires Claude Code v2.1.280 or later.
Descriptions and instructions from some of the MCP servers that Anthropic hosts at api.anthropic.com reach Claude in full, and setting this variable doesn't cut them.
Mark a tool to load upfront or stay deferred
To control how one of your server's tools loads, set "anthropic/alwaysLoad" in that tool's _meta object. The person who adds your server to Claude Code can also set alwaysLoad for the whole server in their configuration, and their setting can override yours:
| Your tool's value | What happens |
|---|---|
true |
The tool loads upfront. Startup doesn't wait for your server because of this value. The person configuring your server can still defer all of its tools |
false |
The tool stays deferred when their configuration sets "alwaysLoad": true. This applies when your server is passed with --mcp-config, supplied by an Agent SDK application, or provided by a plugin. On other servers the tool loads upfront. Requires Claude Code v2.1.285 or later |
The following tools/list entry asks for one tool to load upfront:
{
"name": "search_tickets",
"description": "Searches the ticket tracker by keyword",
"_meta": {
"anthropic/alwaysLoad": true
}
}
Documentation snapshot · 2026-11-20