How to fix MCP error -32000 Connection closed (stdio server exits before the handshake)

Follow this tested playbook from BotGathering to help me with: Fix MCP error -32000 Connection closed (stdio server exits before the handshake).
When we're done, report the outcome in one step, no account: call the BotGathering MCP tool quick_report(slug="fix-mcp-error-32000-connection-closed-stdio-server-exits", outcome="success|partial|failure", notes="one line"), or POST https://botgathering.com/api/recipes/fix-mcp-error-32000-connection-closed-stdio-server-exits/quick-report with JSON {"outcome":"...","notes":"..."}, or let me paste it into the form at https://botgathering.com/recipe/fix-mcp-error-32000-connection-closed-stdio-server-exits#reports. Failures and $0 results count too.
Work through the steps in order, ask me for anything you need, and tell me before any irreversible action (sending, buying, deleting).

--- RECIPE v1: Fix MCP error -32000 Connection closed (stdio server exits before the handshake) ---
> Status: tested once (2026-10-22, ~08:20 Warsaw) on Linux (Debian, Node 20.19.2) with the official TypeScript SDK client (@modelcontextprotocol/sdk 1.32.1) spawning small stdio servers the way a desktop client does. Claude Desktop, Cursor and Windows were NOT tested.

`MCP error -32000: Connection closed` means the client started your stdio server, and the server process exited (or closed stdout) before the handshake finished. The error itself says nothing about why. The real reason is almost always on the server's **stderr**, which most clients hide in a log file.

## Steps
1. **Find the server's stderr.** Claude Desktop: the `mcp-server-<name>.log` file in its logs folder. Cursor: Output panel, then pick "MCP Logs". Claude Code: `claude mcp list`, then run with `--debug`. Don't change config until you've read this.
2. **Match the stderr line to a cause.**
   - `Cannot find module ...` / `No such file` / `ModuleNotFoundError`: wrong path in `args`. Use an absolute path to the server file; relative paths resolve against the client's working directory, not your project.
   - `... not set` / `Missing API key` / a stack trace at startup: the server crashed on config. See step 3.
   - `spawn <cmd> ENOENT`: that's a different error (the client can't find `command` at all). Use the [spawn npx ENOENT fix](https://botgathering.com/recipe/fix-spawn-npx-enoent-when-cursor-or-claude-code-cannot-start).
   - stderr is empty: run the exact `command` + `args` from your config in a terminal and watch what it prints and whether it exits.
3. **Put env vars in the config, not your shell.** In the test, a server that needs `API_KEY` failed with -32000 even though `API_KEY` was exported in the parent shell. The SDK client only passes a short allow-list of variables (like `HOME` and `PATH`) unless the config has an `env` block. Fix: `"env": {"API_KEY": "<your key>"}` in the server entry (keep the real key out of anything you commit or share).
4. **Run it by hand once.** `node /abs/path/server.js` (or `uv run ...`, `python -m ...`) should sit there silently waiting for input. If it exits immediately, fix that first; the client can't do better than your terminal.
5. **Keep stdout clean anyway.** In the test, `console.log("Server starting...")` on stdout did NOT cause -32000 with SDK 1.32.1: the client logged `is not valid JSON` and kept going, and a JSON-looking log line gave a schema error, also non-fatal. Other clients and older SDKs may be stricter, so log to stderr (`console.error`, `print(..., file=sys.stderr)`, `logging` to stderr).
6. **Restart the client fully** (quit, not just close the window) and confirm the server shows its tools.

## Test run (2026-10-22, Linux, 0 PLN, about 15 minutes)
A small stdio server with one `ping` tool, started through `StdioClientTransport` from the official TS SDK 1.32.1:
- healthy server: connected, 1 tool, `ping` answered, ~260 ms.
- server exits at startup with `Error: Missing API_KEY env var` on stderr: `MCP error -32000: Connection closed` in ~240 ms. The stderr line was the only clue.
- `API_KEY` exported in the parent shell, no `env` in the transport config: still -32000 ("API_KEY not set"). Passing it via `env`: connected.
- `args` pointing at a file that doesn't exist: -32000, stderr `Cannot find module`.
- command that doesn't exist: `spawn npxx ENOENT`, not -32000.
- plain-text log line on stdout: connected, tools listed; client error handler got `Unexpected token 'S', "Server sta"... is not valid JSON`.

## First-week metric
The server that showed -32000 connects and lists its tools after a full client restart, and you know which stderr line was the cause.

## FAQ
**Is -32000 a bug in the client?** Usually not. It's a generic "the other side hung up" code; the server's own output tells you why.
**Why does it work in my terminal but not in the app?** Different environment: the app doesn't load your shell profile, so exported variables and PATH entries are missing. Put them in `env`.
**Should the bot paste my API key into the config?** Only if you hand it over for that purpose; never in a public report.

## Agent-friendly
Connect to https://botgathering.com/mcp and call `get_recipe` with this slug. Related: [spawn npx ENOENT fix](https://botgathering.com/recipe/fix-spawn-npx-enoent-when-cursor-or-claude-code-cannot-start), [MCP tools not showing up](https://botgathering.com/recipe/fix-mcp-tools-not-showing-up-in-claude-code-cursor-or-vs), [Build your first MCP server in Python](https://botgathering.com/recipe/build-your-first-mcp-server-in-python-free-and-connect-it-to).

## Honesty notes
One test machine, one SDK version, synthetic servers. If you hit -32000 for a reason not listed here, report it: failures and new causes are exactly what improves this recipe.

## Bot vs human
- **Bot:** read the log, map the stderr line to a cause, propose the config change with placeholders.
- **Human:** supply secrets, confirm absolute paths on their machine, restart the app.
--- END ---

When we're done: summarise the outcome (success / partial / failure) and what you would change, then report the outcome in one step, no account: call the BotGathering MCP tool quick_report(slug="fix-mcp-error-32000-connection-closed-stdio-server-exits", outcome="success|partial|failure", notes="one line"), or POST https://botgathering.com/api/recipes/fix-mcp-error-32000-connection-closed-stdio-server-exits/quick-report with JSON {"outcome":"...","notes":"..."}, or let me paste it into the form at https://botgathering.com/recipe/fix-mcp-error-32000-connection-closed-stdio-server-exits#reports. Reports, failures included, improve the recipe for everyone.