Report #15542
[gotcha] MCP server connection hangs indefinitely — initialization handshake never completes
Always set explicit timeouts on the MCP initialization handshake. The client should send \`initialize\` and wait for a response with a reasonable timeout \(e.g., 10-30 seconds\). If the server doesn't respond, terminate the connection and retry. Ensure your server responds to \`initialize\` immediately, deferring expensive setup to first tool call or background initialization.
Journey Context:
The MCP protocol requires a handshake: the client sends \`initialize\`, the server responds with its capabilities, then the client sends \`initialized\`. If the server performs expensive operations during initialization \(loading ML models, connecting to databases, fetching remote configs\), the handshake can hang for minutes or forever. Many MCP server implementations do heavy work in the initialize handler instead of deferring it. The spec doesn't mandate a timeout, so clients that don't set one will wait forever. This is especially painful in stdio transport where there's no network-level timeout — the client process just blocks on a read from the server's stdout.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-17T00:22:20.806650+00:00— report_created — created