claude-code - 💡(How to fix) Fix [DOCS] MCP docs missing `alwaysLoad` server configuration option [1 comments, 1 participants]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/mcp

Section/Topic

Scale with MCP Tool Search and the MCP server configuration examples for .mcp.json

Current Documentation

The docs currently say:

Tool search is enabled by default. MCP tools are deferred rather than loaded into context upfront, and Claude uses a search tool to discover relevant ones when a task needs them. Only the tools Claude actually uses enter context.

Control tool search behavior with the ENABLE_TOOL_SEARCH environment variable:

| Value | Behavior | | (unset) | All MCP tools deferred and loaded on demand. Falls back to loading upfront on Vertex AI or when ANTHROPIC_BASE_URL is a non-first-party host | | true | All MCP tools deferred, including on Vertex AI and for non-first-party ANTHROPIC_BASE_URL | | auto | Threshold mode: tools load upfront if they fit within 10% of the context window, deferred otherwise | | false | All MCP tools loaded upfront, no deferral |

And the .mcp.json config documentation currently lists expansion/examples for fields like:

• command - The server executable path
• args - Command-line arguments
• env - Environment variables passed to the server
• url - For HTTP server types
• headers - For HTTP server authentication

No documentation currently explains an alwaysLoad field on individual MCP server configs.

What's Wrong or Missing?

Changelog v2.1.121 added alwaysLoad to MCP server config: when true, all tools from that server skip tool-search deferral and are always available.

The current docs only describe global tool-search behavior through ENABLE_TOOL_SEARCH; they do not document:

• where alwaysLoad belongs in MCP server config
• an example showing the field in .mcp.json or equivalent server config
• how it changes behavior relative to the default deferred tool-search flow
• how users should choose between alwaysLoad and global ENABLE_TOOL_SEARCH settings

That leaves a new user-facing MCP configuration option discoverable only from the changelog.

Suggested Improvement

Add alwaysLoad to the MCP configuration docs and to the Tool Search section, with a short example such as:

{
"mcpServers": {
"github": {
"type": "http",
"url": "https://api.githubcopilot.com/mcp/",
"alwaysLoad": true
}
}
}

The docs should explicitly state that alwaysLoad: true forces that server's tools to skip tool-search deferral and stay available from session start, and clarify how this interacts with global ENABLE_TOOL_SEARCH behavior.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 4 pages affected

Source: Changelog v2.1.121

Exact changelog entry:

Added alwaysLoad option to MCP server config — when true, all tools from that server skip tool-search deferral and are always available