Codex CLI MCP startup fails for local stdio server even though manual initialize succeeds

Open 💬 2 comments Opened Apr 7, 2026 by zdenda-balcar-clevertify

What version of Codex CLI is running?

codex-cli 0.118.0

What subscription do you have?

Business

Which model were you using?

gpt-5.4

What platform is your computer?

Linux 6.6.87.2-microsoft-standard-WSL2 x86_64 x86_64

What terminal emulator and version are you using (if applicable)?

Linux terminal emulator (bash shell)

What issue are you seeing?

Codex CLI fails to complete MCP startup/handshake for a local stdio MCP server on Linux.

I tested a local Python MCP server that is launched successfully by Codex. The server starts, completes its own
initialization quickly, and is able to respond correctly to a manual MCP initialize request over stdio outside Codex.

However, when launched by Codex, startup fails with one of these errors:

``text
MCP client for
test-server timed out after 60 seconds. Add or adjust startup_timeout_sec` in your config.toml:
[mcp_servers.test-server]
startup_timeout_sec = XX

and in another variant:

MCP startup failed: handshaking with MCP server failed: connection closed: initialize response

I instrumented the server with simple startup logging. In the timeout case, the process is started by Codex and server
initialization completes, but no MCP request is ever received from Codex. In the handshake-failure case, Codex reports
handshake failure even though the same server responds correctly to manual initialize outside Codex.

What steps can reproduce the bug?

  1. Configure a local stdio MCP server in Codex.
  2. Start Codex in a Linux shell.
  3. Observe MCP startup failure.

I reproduced this with both:

  • project-scoped config in .codex/config.toml
  • global config via codex mcp add

Example project-scoped config:

```toml
[mcp_servers.test-server]
command = "my-mcp-server"
env_vars = ["SOME_REQUIRED_ENV"]
startup_timeout_sec = 60

I also reproduced it with a global wrapper-based registration.

Important observations:

  • the MCP server process starts successfully
  • the server completes startup quickly
  • the same server responds correctly to a manual stdio MCP initialize request
  • in the timeout case, Codex never appears to send any MCP message to the server
  • in the handshake-failure case, Codex reports connection closed: initialize response

Manual validation outside Codex:

  • manual stdio initialize request succeeds
  • tools/list succeeds

What is the expected behavior?

Codex should complete MCP startup successfully for a local stdio MCP server that starts correctly and responds to
initialize.

If the server process is launched successfully and the server can answer MCP requests, Codex should finish the handshake
and make the server available in the session.

Additional information

  • codex mcp list / codex mcp get show the MCP server as enabled.
  • The issue reproduces on Linux with codex-cli 0.118.0.
  • Manual stdio testing against the same server shows that the server returns a valid initialize response immediately.
  • This appears more likely to be a Codex MCP client issue than a server startup issue, because the process launches

successfully and the server works when tested directly outside Codex.

I can provide:

  • MCP server startup logs
  • a minimal reproducible Python stdio MCP server if needed

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗