MCP lifecycle guide
MCP Connection and Handshake Errors
Choose an MCP fix by launch, initialize, HTTP/SSE transport, or tool-result stage instead of treating every failure as configuration.
Match the complete nested error, client surface, operating system, and version. Similar outer messages can hide different failures.
Safety boundary: redact credentials and identify the failing lifecycle stage before changing packages, timeouts, authentication, or transport settings.
Choose by stage
Process launch and environment
The server never reaches MCP initialize because the executable, environment, or allowed directory is wrong.
Claude Code MCP spawn npx ENOENT on Windows
SPAWN ERROR: ENOENT spawn npx ENOENTFix Claude Code MCP plugins that fail with SPAWN ERROR: ENOENT spawn npx ENOENT on native Windows.
Open exact fix →Claude Desktop passes a literal ${VAR} to an MCP server
MCP server receives the literal string ${VAR}Diagnose Claude Desktop on Windows when an MCP env value stays as a literal ${VAR}, while the same user-scope configuration expands in Claude Code CLI.
Open exact fix →MCP Filesystem disconnects when an allowed directory is missing
Error accessing directory ... ENOENT: no such file or directory, stat ...Fix MCP Filesystem ENOENT and Server disconnected errors caused by one missing, renamed, or offline allowed directory.
Open exact fix →Choose by stage
Initialize and capability negotiation
The process starts but the client and server do not complete the MCP initialize handshake.
Claude Desktop cancels MCP initialize after 60 seconds
Message from client: method="notifications/cancelled"Diagnose Claude Desktop MCP initialize cancellations when an npx, uvx, or pipx package runner spends more than 60 seconds resolving dependencies.
Open exact fix →Codex bundled MCP fails with JSON-RPC error -32603
MCP startup failed: handshaking with MCP server failed: JSON-RPC error: -32603Diagnose Messages and Computer History MCP startup failures caused by an experimental capability compatibility mismatch.
Open exact fix →Codex app-server initialize handshake times out in WSL mode
Codex app-server initialize handshake timed outDiagnose Codex Desktop WSL startup when the app-server initialize handshake times out and nested logs show bwrap relocation ENOENT.
Open exact fix →Choose by stage
HTTP, SSE, and returned tool results
Initialization can succeed while a stream, endpoint, or result-submission path fails later.
MCP fails to open an SSE stream with Not Found
StreamableHTTPError: Streamable HTTP error: Failed to open SSE stream: Not FoundFix MCP Streamable HTTP clients that send GET to an MCP endpoint and fail with StreamableHTTPError: Failed to open SSE stream: Not Found.
Open exact fix →MCP SSE stream disconnects with TypeError: terminated
SSE stream disconnected: TypeError: terminatedDiagnose MCP Streamable HTTP or SSE connections that repeatedly disconnect with TypeError: terminated.
Open exact fix →Claude Desktop MCP tools fail with side_channel_waiting_key_absent
side_channel_waiting_key_absentDiagnose Claude Desktop when every MCP tool shows Failed to call tool but server logs succeed and tool_result returns side_channel_waiting_key_absent.
Open exact fix →idle timeout waiting for SSE hides response.failed
idle timeout waiting for SSEDiagnose Codex CLI 0.153.4 when an SSE terminal failure is replaced by a later idle-timeout message.
Open exact fix →