Codex: MCP client timed out after 30 seconds

What it means

When Codex starts, it starts every configured MCP server and waits for each to answer. A server that does not answer in time is dropped for that session. In the Codex CLI 0.164.0 terminal UI the warnings are behind F2. With a server that never answered, we got:

MCP client for `hang` timed out after 30 seconds. Add or adjust `startup_timeout_sec` in your config.toml:
[mcp_servers.hang]
startup_timeout_sec = XX

MCP startup incomplete (failed: ghost, hang)

In 0.164.0 the default was 30 seconds. A public report (in the sources below) shows timed out after 10 seconds, so read the number in your own message rather than trusting a guide.

In codex exec we saw no warning at all: the server’s tools were simply missing.

The server is slow to start

Servers on the JVM, servers that load a model, and packages that npx or uvx download on first run can take longer than the default. Raise the limit for that server:

[mcp_servers.my-server]
command = "npx"
args = ["-y", "some-mcp-server"]
startup_timeout_sec = 90

With startup_timeout_sec = 5 the message changed to timed out after 5 seconds, so this key works in 0.164.0. We also tried startup_timeout_ms = 4000, which some older guides use; it had no visible effect.

For npx servers, install the package once in a terminal first, so the first Codex start does not include the download.

The server never answers

If raising the timeout does not help, the server is stuck rather than slow. Run the exact command in a terminal: it should start and wait without printing anything to stdout. Then test it with the Inspector. Common causes are a prompt waiting for input, a missing environment variable that makes it wait on a connection, and output on stdout.

“failed to start” instead of “timed out”

The same warning panel shows other startup failures with the server name:

MCP client for `ghost` failed to start: MCP startup failed: No such file or directory (os error 2)

means the command does not exist: see spawn … ENOENT. A server that exits during startup shows handshaking with MCP server failed: connection closed: initialize response: see Connection closed.

Related

• Connect an MCP server to Codex