claude-code - 💡(How to fix) Fix MCP server config: support `eagerLoad` to pre-load tool schemas at session start

Problem

MCP tools are currently "deferred" — only their names are known at session start. To call any MCP tool, the model must first call ToolSearch to load the schema:

// Every session, every relevant tool:
ToolSearch("select:mcp__my_server__get_snapshot")
// only then:
mcp__my_server__get_snapshot(...)

This is a reasonable optimization for optional/occasional tools, but it creates friction for infrastructure MCP servers that should be usable from the very first turn — e.g. a memory broker, a task queue, or a shared state store that every session needs immediately.

Proposed solution

Add an eagerLoad (or similar) flag to mcpServers in settings.json:

"mcpServers": {
  "memorybroker": {
    "type": "http",
    "url": "http://localhost:8000/mcp",
    "headers": { "X-API-Key": "..." },
    "eagerLoad": true
  }
}

When eagerLoad: true, Claude Code would fetch and inject the full tool schemas at session start (alongside CLAUDE.md loading), so the model can call them without a prior ToolSearch.

Why this matters

• Infrastructure MCPs (memory brokers, task queues, shared state) are used on every turn, not occasionally. Requiring ToolSearch on every session start adds a mandatory round-trip before any real work begins.
• The current workaround — injecting a ToolSearch instruction via a SessionStart hook — works but is fragile and indirect. A first-class config option is cleaner.
• CLAUDE.md instructions to "always ToolSearch at startup" are behavioral guidance, not enforcement; they can be missed or deprioritized.

Alternatives considered

• SessionStart hook with ToolSearch instruction: Works, but requires the model to follow the instruction — not guaranteed.
• Hardcoding descriptions in CLAUDE.md: Static, gets stale, not the right layer.
• Always eager-load all MCPs: Too expensive for large tool sets; opt-in per server is the right granularity.

Environment

• Claude Code CLI on Linux/WSL2
• MCP server type: HTTP
• Use case: shared memory broker used by 6+ AI agents across multiple hosts