Pit record
MCP error -32000: Connection closed means the stdio server died before the handshake
MCP error -32000: Connection closed is a generic 'the stdio server process did not start' signal, not a protocol bug. Diagnose by running the exact configured command+args+env in a terminal; the usual concrete causes are PATH, npmrc registry, npx cache, Windows cmd /c, or a missing build.
Markdown mirror | Canonical source
Fast answer
Problem: client UI shows MCP error -32000: Connection closed
Root cause: The client spawns the configured command and speaks JSON-RPC over stdio.
Fix first: Reproduce outside the client: run the exact command + args from the config in a terminal with the same env.
Verify: Reconnect from the client after fixing the underlying cause.
Queries this answers
- GitHub MCP Server Fails to Start: 'npx' Command Error and Connection Closed -32000
- GitHub MCP Server Fails to Start: 'npx' Command Error and Connection Closed (-32000) fix
- GitHub MCP Server Fails to Start: 'npx' Command Error and Connection Closed (-32000) root cause
- Fix 'Client Closed' Error by Correcting npm Config
- Fix 'Client Closed' Error by Correcting npm Config fix
- Fix 'Client Closed' Error by Correcting npm Config root cause
- MCP error -32000: Connection closed means the stdio server died before the handshake
- MCP error -32000: Connection closed means the stdio server died before the handshake fix
Record metadata
| Status | verified |
|---|---|
| Confidence | high |
| Created | 2026-06-21 |
| Updated | 2026-06-21 |
| Last verified | 2026-06-21 |
| Affected tools | claude-desktop, cursor, cline, mcp-server |
| Tags | mcp, stdio, startup, error-32000, npx, diagnosis |
Common search queries
- mcp-error-32000-connection-closed-server-failed-to-start
- mcp error 32000 connection closed server failed to start
- MCP error -32000: Connection closed means the stdio server died before the handshake
- MCP error -32000: Connection closed means the stdio server died before the handshake fix
- MCP error -32000: Connection closed means the stdio server died before the handshake root cause
- stdio
- startup
- error-32000
- diagnosis
- claude-desktop
- cursor
- cline
Symptoms
- client UI shows MCP error -32000: Connection closed
- sometimes preceded by locale text like 'npx' is not recognized as an internal or external command
- the configured command and args run fine when pasted into a terminal
- no useful server-side logs because the process never reached startup
Environment
| constraints | GUI/editor MCP client spawning a stdio server, command resolved via PATH |
|---|
Root cause
- The client spawns the configured command and speaks JSON-RPC over stdio.
- If the process cannot be found, crashes on launch, or writes non-protocol text to stdout, the transport closes and the client reports -32000: Connection closed.
- The code is generic: it reports that the connection died, not why.
Fix
Reproduce outside the client: run the exact command + args from the config in a terminal with the same env.
Any error or non-JSON-RPC output you see there is the real failure.
Check the specific causes, each tracked separately: PATH not inherited, wrong user-level npmrc registry, corrupted npx cache, Windows needing cmd /c npx, or a missing local build.
Use absolute paths for the interpreter and script in the config to remove PATH ambiguity.
Ensure the server writes diagnostics to stderr, never stdout, since stdout is the JSON-RPC channel.
Verification
Reconnect from the client after fixing the underlying cause.
Expected: Tool discovery succeeds with no -32000 in the client log.
Workarounds
- Pin absolute interpreter and script paths in the config.
- Pre-install the server package globally so npx does not need to resolve or download it at launch.
Anti-patterns
- Filing a protocol bug for -32000 before running the command manually.
- Reinstalling the server package repeatedly when the package was never the problem.
- Writing debug output to stdout from a stdio MCP server, which corrupts the JSON-RPC stream.
Sources
No matching fix?
If this record is close but does not solve the user's failure, create a safe unresolved-pit report instead of guessing. Include exact symptoms, environment, attempted fixes, and the record ids already checked.