OpenAI Codex CLI error
Codex CLI: MCP client for X failed to start: handshaking with MCP server failed...
MCP client for `X` failed to start: handshaking with MCP server failed: connection closed: initialize responseStatus: OpenLast verified 3 documented fixes3 sources
What it means
Codex started or connected to the MCP server, but the connection closed before the server answered the MCP initialize request.
Causes
- Maintainer gpeal (#6020): the reported failures were either unsupported SSE servers or incorrect configuration.
- Maintainer gpeal: "Codex only supports streamable http servers. SSE is deprecated and we may or may not backport support."
How to fix it
- Fix 1.
Point Codex at the server's streamable HTTP endpoint instead of an SSE endpoint (gpeal noted Linear's updated server is at https://mcp.linear.app/mcp).
TOML[mcp_servers.linear] url = "https://mcp.linear.app/mcp" - Fix 2.
Run the server's command in a terminal outside Codex; it should start, appear to run without doing anything, show no errors and not exit on its own (maintainer gpeal on #6020).
- Fix 3.
For servers that use OAuth, sign in separately (official MCP docs).
Terminalcodex mcp login <server-name>
More Codex CLI errors
All 14 Codex CLI errorsstream disconnected before completion: stream closed before response.completedStatus: Workaroundstream disconnected before completion: error sending request for url (https://chatgpt.com/backend-api/codex/responses)Status: OpenError running remote compact task: stream disconnected before completion: error sending request for url (https://chatgpt.com/backend-api/codex/responses/compact)Status: Fixed in releaseSelected model is at capacity. Please try a different model.Status: By designYour access token could not be refreshed because your refresh token was already used. Please log out and sign in again.Status: Fixed in releaseCodex ran out of room in the model's context window. Start a new thread or clear earlier history before retrying.Status: Fixed in releaseError logging in: Port 127.0.0.1:1455 is already in useStatus: WorkaroundToken exchange failed: token endpoint returned status 403 ForbiddenStatus: Workaround
Related reading
- How to Make Claude Code 10x Better at Design: Image and Video Assets From the Agent LoopMake Claude Code better at design by putting image and video generation in the agent loop with Higgsfield MCP and CLI, so sites ship with real assets.
- Codex and Claude Code in July 2026: Agent Controls Are the FeatureCodex and Claude Code July 2026 updates compared: why approval modes, resumable work, MCP auth, artifacts and review surfaces now matter as much as models.
- AgentCanvas is a visual adapter for Claude Code and CodexAgentCanvas is a visual adapter for Claude Code and Codex that puts artifacts, decisions and handoffs on one board, so the next agent or human can see them.
- GitHub Copilot Agent Finder: What ARD Means for Third-Party AI Tools in 2026GitHub Copilot Agent Finder discovers and invokes MCP servers, skills and agents like Claude and Codex. How the open ARD spec changes AI tool integration.
- AgentMemory Is Useful Only If You Audit What It RemembersAgentMemory gives Claude Code, Codex and Cursor persistent local memory. The real adoption test is whether your team can inspect, prune and govern it.
- 10 Trending AI Dev Tools, Week of April 28 2026From Claude Opus 4.7 and GPT-5.5 to Andrej-karpathy-skills and EvoMap - the AI dev tools actually shipping the last 30 days, with commands, links, and pricing.
FAQ
What does "MCP client for X failed to start: handshaking with MCP server failed..." mean in Codex CLI?
Codex started or connected to the MCP server, but the connection closed before the server answered the MCP initialize request.
How do I fix "MCP client for X failed to start: handshaking with MCP server failed..."?
There are 3 documented fixes. Start with the first: Point Codex at the server's streamable HTTP endpoint instead of an SSE endpoint (gpeal noted Linear's updated server is at https://mcp.linear.app/mcp).
Is this Codex CLI error fixed?
Status: Open. Still open upstream. Any documented fixes are workarounds so far. Affected versions: Reported on codex-cli 0.53.0 (#6020)
Sources
Last verified against 3 sources: official docs, maintainer replies and release notes.
Newsletter
Fixes for the tools you use, weekly
One email per week. New coding agent releases, what broke, and how developers are working around it.