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 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

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗