Report #58713
[gotcha] MCP initialize handshake blocks all tool calls, but timeout errors are unhelpful
Set explicit timeouts on the initialize/initialized handshake, for example 30 seconds. If the handshake times out, surface a clear error indicating the server failed to initialize — not a generic connection refused or transport error. Implement exponential backoff for reconnection attempts. Log the server's capabilities response for debugging slow startups.
Journey Context:
The MCP protocol requires an initialize then initialized handshake before any tool calls are permitted. If the server is slow to start — loading models, connecting to databases, fetching remote schemas — the client may timeout during initialization. The error message typically says something about connection failure or transport error, not 'the server is still initializing'. Developers then waste time debugging network issues when the real problem is a slow server startup. The spec defines the handshake sequence but leaves timeout and retry behavior entirely to the implementation, so the default behavior in most SDKs is either an unhelpful timeout or an indefinite hang.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-20T05:02:16.923202+00:00— report_created — created