✗ MCP client for `X` failed to start: handshaking with MCP server failed: connection closed: initialize response

This is among the most-reported MCP failures in the Codex tracker — issue #6020 has been open since October 31, 2025, with 42 comments, 34 reactions, and activity through June 2026. The message is an umbrella: Codex spawned your configured server, and the process either died or wrote something other than a JSON-RPC initialize response before the handshake finished.

Symptoms

• codex prints the warning for one server — or all of them, as in the original report, where nine configured servers failed together.
• The same server runs fine under other MCP clients — in #16229 it worked with the official MCP SDK client but not the Codex desktop app.
• On Windows, servers launched via npx, pnpm, or corepack fail while absolute executable paths succeed.

Cause

Anything that kills the child process or corrupts its stdout produces this one error. The #6020 thread documents the recurring triggers: Windows .cmd shims that Rust’s process spawn can’t execute directly, unsupported Node versions, a corrupt ~/.npm/_npx cache, servers that log to stdout (which the stdio transport reserves for JSON-RPC), cold starts blowing the 10-second default handshake timeout, and SSE endpoints — maintainer gpeal wrote in the thread that “Codex only supports streamable http servers. SSE is deprecated and we may or may not backport support.”

Fix

1. Run the server standalone. Paste the exact command + args into a terminal. #16309 hit a neighboring startup failure (Permission denied rather than connection closed) from a launcher that simply wasn’t executable.
2. On Windows, update Codex first — PR #3828 taught the CLI to resolve .cmd/.bat scripts to their full paths before spawning. If it still fails, use an absolute path: node.exe plus the server’s JS entry script worked in #16229. A #6020 commenter succeeded with command = "cmd", args = ["/c", "npx", ...], though mcp.directory recommends the absolute path because the extra shell eats into the handshake budget.
3. Pin Node 20 or 22 and clear ~/.npm — both reported as fixes in the thread.
4. Raise the timeout with startup_timeout_sec = 30 under [mcp_servers.X] (the default is 10), and pre-warm cold npx installs by running the package once first.
5. Keep server logs on stderr. Two #6020 reporters fixed the handshake by moving logging off stdout.
6. For remote servers, use the /mcp streamable-HTTP endpoint, not /sse, per the maintainer statement above.
7. Declare secrets under [mcp_servers.X.env] or whitelist them with env_vars, which the docs define as environment variables “to allow and forward” — variables you don’t list don’t reach the server.

Affected versions

Reports start at codex-cli 0.53.0 in #6020 (October 2025). The Windows script-spawn bug was fixed in the CLI that November, but the desktop app showed the same failure in March 2026, and #6020 remains open. We’ll update this page when it closes.

Facts on this page verified July 14, 2026.