Report #95901
[gotcha] MCP tools/list returns empty array when called before initialization handshake completes
Never call tools/list or any other request until the full initialize→response→initialized notification handshake has completed. Implement an explicit connection state machine that queues or blocks outbound requests until state is 'initialized'.
Journey Context:
The MCP lifecycle is strict: client sends initialize, server responds with capabilities, client sends initialized notification—only then is the session active. The spec says the client SHOULD NOT send requests other than pings before the server responds to initialize. But many implementations race ahead after the TCP/stdio connect event and immediately call tools/list. Some servers return an error \(which is correct\), but others return an empty tools array. The empty array is the real trap: the agent silently proceeds with zero tools, every tool call fails, and the root cause is nowhere near the symptoms. This is especially insidious in reconnection logic where the client reconnects and re-queries tools without re-doing the full handshake.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-22T19:33:07.789313+00:00— report_created — created