claude-code - 💡(How to fix) Fix stdio MCP server tools dropped when initialize exceeds probe timeout

Summary

When a stdio MCP server's initialize handshake takes longer than the Claude Code session-init probe timeout, the server's tools are silently dropped from the deferred-tool registry. The server is later marked ✓ Connected (sometimes inconsistently between claude mcp list and claude mcp get), but ToolSearch returns No matching deferred tools found for every mcp__<server>__* lookup for the rest of the session. Restarting the session does not help — the same race fires on every fresh probe.

Reproduces deterministically with code-context-mcp v2.0.4 (PyPI) on Windows, where the server's initialize legitimately takes ~16 s on a warm Hugging Face cache (loading sentence-transformers/all-MiniLM-L6-v2). Likely affects any stdio MCP server whose cold-start exceeds a few seconds.

Environment

• Claude Code CLI: 2.1.131
• OS: Windows 11 Pro 26200
• MCP server type: stdio
• Server cold-init: ~16 s (verified via code-context doctor mcp)
• .mcp.json registered at project scope

Steps to reproduce

1. Install a slow-initializing stdio MCP server (e.g., pip install code-context-mcp then add to .mcp.json).
2. Open a fresh Claude Code session in the project.
3. Inspect the system-reminder at session start — the slow server appears in the "still connecting" list but its mcp__<server>__* tools never make it to the deferred-tools list.
4. Run ToolSearch(query="select:mcp__<server>__<tool>") — returns No matching deferred tools found even minutes later.

Expected

The 8 (or N) tools advertised by the server are eventually discoverable via ToolSearch once the server completes initialize and responds to tools/list.

Actual

Tools are never registered. The server reports ✓ Connected per claude mcp list, but ToolSearch and the deferred-tools registry remain empty.

Evidence

In one fresh session (2026-05-18):

Five ToolSearch queries with different syntaxes all miss:

ToolSearch(query="select:mcp__code-context__search_repo,...") → No matching deferred tools found
ToolSearch(query="code-context search")                       → returns unrelated tools, no code-context entry
ToolSearch(query="+code-context")                             → returns unrelated tools, no code-context entry
ToolSearch(query="search_repo find_definition")               → No matching deferred tools found
ToolSearch(query="recent_changes get_summary explain_diff")   → No matching deferred tools found

Server is healthy server-side (code-context doctor mcp --timeout 30):

initialize (open stdio + handshake)   ok    (16.40s)
list_tools                            ok    (0.00s)
Tools advertised: 8/8 expected

claude mcp list / claude mcp get flip between Connected and Failed in back-to-back invocations in the same session, strongly suggesting the host's probe has a timeout shorter than 16 s:

Hypothesis

The deferred-tool registry is populated from the first session-init probe. That probe's timeout is shorter than the server's cold initialize, so the probe times out, and the registry is filled without this server's tools. The server eventually completes initialize on a later probe and is marked Connected, but the registry is never repopulated.

Proposed fixes (any one would resolve this)

1. Raise the session-init probe timeout to ≥ 60 s, or make it configurable per-server in .mcp.json (e.g., an initTimeoutMs field).
2. Re-poll tools/list opportunistically when a stdio MCP server transitions Failed → Connected in the registry, and update the deferred-tools index.
3. Surface the probe timeout failure to the user during session start (visible in /mcp or the system-reminder), with a hint to restart or wait. Today the failure is silent.

Workaround

Operators can confirm server-side health independently with code-context doctor mcp (a v2.0.4 subcommand that drives the real MCP handshake against the same binary and verifies all tools come back from tools/list). When doctor mcp passes but Claude Code shows no tools, the issue is host-side.

Related artefacts

• Full validation report available on request (lives in the code-context-mcp repo at docs/superpowers/plans/sprints/SESSION-PROMPT-v204-validation.md).
• Server's stdout/stderr at probe time emits register: wiring 8 MCP tools on Server instance followed by list_tools() called by host; returning 8 tool descriptors — log lines added specifically to disambiguate host-side vs server-side bugs.