MCP server config: support `eagerLoad` to pre-load tool schemas at session start
Resolved 💬 2 comments Opened May 30, 2026 by unagikudari Closed Jun 3, 2026
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
ToolSearchon every session start adds a mandatory round-trip before any real work begins. - The current workaround — injecting a ToolSearch instruction via a
SessionStarthook — 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
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗