Codex MCP server failed to start or timed out: fixes

Codex has two MCP startup errors, and they take different fixes. "MCP client for name timed out after N seconds" is a slow server: give it more time with startup_timeout_sec in its [mcp_servers.<name>] table. "MCP client for name failed to start:" plus an error is a broken command or handshake, and more time won't fix that.

We read both messages in the Codex source at release 0.164.0 (23 October 2026) and compared them with OpenAI's MCP page for Codex on 24 October 2026. Page and code give different default timeouts: 10 and 60 seconds on the page, 30 and 300 in rmcp_client.rs.

Which Codex MCP error do you have?#

Codex 0.164.0 writes MCP startup failed: between "failed to start:" and the underlying error, so read further along the line for one of these fragments.

Codex sorts the message itself: an error that contains "timed out handshaking with MCP server", "MCP client startup timed out" or "request timed out" becomes the timeout line, and everything else follows "failed to start:" as the server or the operating system gave it (startup.rs).

Codex MCP server timed out after 10 or 30 seconds#

OpenAI's page still says startup_timeout_sec defaults to 10 seconds. The code has used 30 since release 0.118.0 (31 March 2026), whose notes say local servers "get a longer startup window"; at 0.164.0 that is DEFAULT_STARTUP_TIMEOUT in rmcp_client.rs. Go by the number in your message, because Codex prints the timeout that was in force for that server.

One server gets longer with the key in its own table in ~/.codex/config.toml.

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
startup_timeout_sec = 60

First runs of npx and uvx servers are the usual slow starters, since the package downloads before the server can answer. Run the same command once in a terminal and the cache is filled; later starts are quicker. A timeout that comes back at whatever value you try means the server is waiting on something, such as a sign-in page, a prompt or a database it can't reach, and the next section applies.

A slow server doesn't hold up your session. While it builds the first tool list, Codex waits 1,000 ms for optional servers and leaves out the tools of any server that isn't ready yet, unless it already holds a cached tool list for it. Since release 0.151.0 you can change that wait with the top-level mcp_optional_startup_grace_ms, and 0 makes Codex wait each server's full startup_timeout_sec. If you would rather Codex stopped than carried on without a server, set required = true in its table: OpenAI's page says startup then fails when that server can't initialise.

MCP client failed to start: find the real error#

1. Run the command yourself. Paste command and args from the table into a terminal opened in the folder you use Codex in. A healthy stdio server prints nothing to stdout (some log a line to stderr) and sits waiting for input; Ctrl+C gets you out. A missing package, a wrong Node or Python version or a crash shows up on screen.
2. Check what the server can see. A local server doesn't get your whole shell. On macOS and Linux the DEFAULT_ENV_VARS list in utils.rs passes on HOME, LOGNAME, PATH, SHELL, USER, LANG, LC_ALL, TERM, TMPDIR, TZ and macOS's __CF_USER_TEXT_ENCODING. Certificate settings such as SSL_CERT_FILE and NODE_EXTRA_CA_CERTS go along if you set them, and so does whatever you set in env or name in env_vars. A GITHUB_TOKEN exported in .zshrc stays behind until the table says env_vars = ["GITHUB_TOKEN"].
3. Use absolute paths. Codex resolves a relative path in args from wherever it starts the server, so the path breaks the first time you open Codex in another folder. Write the full path, or set cwd in the table.
4. Keep stdout clean. The MCP specification says a stdio server "MUST NOT write anything to its stdout that is not a valid MCP message"; logs go to stderr. A banner or a stray print on stdout corrupts the stream Codex reads. A server that crashes before it answers usually ends in the "connection closed: initialize response" line.
5. Check the result. codex mcp list shows what is configured, and /mcp inside a session shows which servers are running.

Codex MCP "program not found" on Windows#

"program not found" is Windows saying the command isn't on the PATH Codex handed to the server. In 2025 Windows users reported it for npx servers, because npx on Windows is the script npx.cmd (issue 2945). Since release 0.59.0 (19 November 2025) Codex looks a bare command such as npx up through PATH and PATHEXT and finds the .cmd itself, so on a current version the message means the command really isn't there.

1. Run where.exe npx in the PowerShell window you start Codex from. If it prints nothing, Node.js isn't installed or isn't on that terminal's PATH.
2. Just installed Node.js? Open a new terminal, because a window that was already open keeps the PATH it started with.
3. Or write the full path and skip the lookup. Inside single quotes it is a TOML literal string, where backslashes need no escaping.

[mcp_servers.context7]
command = 'C:\Program Files\nodejs\npx.cmd'
args = ["-y", "@upstash/context7-mcp"]

If you run Codex inside WSL, the server is a Linux program and needs Node.js installed inside WSL; the Windows copy doesn't count. Codex CLI on Windows covers when to pick native PowerShell over WSL.

A tool call times out after the server starts#

tool_timeout_sec is a limit on each tool call and has nothing to do with startup. The page says 60 seconds. Release 0.141.0 (18 June 2026) raised it in code to 300 seconds, which is DEFAULT_TOOL_TIMEOUT in rmcp_client.rs at 0.164.0. A slow database query or a long browser run that passes it fails with timed out awaiting tools/call; if that server's calls really run that long, put tool_timeout_sec = 600 in its table.

Claude Code has its own names for all of this (MCP_TIMEOUT, a per-server timeout, claude mcp get); see Claude Code MCP server failed to connect for that side. Setting up a server in Codex from scratch, with codex mcp add and OAuth, is in how to add an MCP server to Codex CLI, and the other config.toml keys are in our config.toml guide.

How Shuriken does it#

Codex and Claude Code each keep their own MCP list, so a server that works in one still has to be set up, and debugged, in the other. Shuriken keeps one list for both. In Global MCPs you add a server once, choose the projects it belongs to and sign in to it once; every Codex and Claude Code chat in those projects is handed the server when it starts, on any of your accounts, and the sign-in follows you to your other computers sealed.

Each server in that list carries a reading for the computer the project lives on: Ready; Not starting, with the error the server gave; Missing on that device when npx or uvx isn't installed, with an Install button; Needs a secret when a ${VAR} in its config is set nowhere there; or Needs sign-in. Test connection starts the server, does the real MCP handshake and says "Connected in N ms" or what went wrong, such as "The server didn't answer in time". None of these checks calls a model. If you want one MCP list for both agents, download Shuriken.