# Codex MCP server failed to start or timed out: fixes > In Codex, "MCP client failed to start" means the command or handshake broke; "timed out after N seconds" means a slow server: raise its startup timeout. Source: https://shuriken.sh/guides/codex-mcp-server-failed-to-start Codex reports two different MCP failures. "Timed out after N seconds" means the server was too slow to start, so give it a longer startup timeout in its config.toml table; "failed to start" plus an error means the command or the handshake broke, and a longer timeout won't help. By Shuriken Updated 27 October 2026 6 min read **Contents** 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.] 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](https://learn.chatgpt.com/docs/extend/mcp?surface=cli) 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. | The message contains | What happened | Fix | | --- | --- | --- | | timed out after 30 seconds. Add or adjust startup_timeout_sec | The server started but didn't finish the MCP handshake in time | Raise startup_timeout_sec , or warm the package cache first | | failed to start … program not found | Windows couldn't find the command | Put it on PATH , or write the full path | | failed to start … No such file or directory (os error 2) | The same on macOS or Linux | Same fix | | failed to start … handshaking with MCP server failed … connection closed: initialize response | The server exited, or closed its output, before answering | Run the command by hand and read what it prints | | MCP server is not logged in. Run codex mcp login | A remote server wants an OAuth sign-in | Run codex mcp login | | timed out awaiting tools/call after 300s | The server started, but one tool call ran too long | Raise tool_timeout_sec | 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](https://github.com/openai/codex/blob/rust-v0.164.0/codex-rs/codex-mcp/src/connection_manager/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. 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 # - 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. - 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](https://github.com/openai/codex/blob/rust-v0.164.0/codex-rs/rmcp-client/src/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"]. - 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. - Keep stdout clean. The [MCP specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports) 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. - Check the result. codex mcp list shows what is configured, and /mcp inside a session shows which servers are running. Shuriken keeps one MCP list for all your agents, and an MCP sign-in follows you to every account and computer. [Download](https://shuriken.sh/download) ## 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](https://github.com/openai/codex/issues/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. - 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. - Just installed Node.js? Open a new terminal, because a window that was already open keeps the PATH it started with. - Or write the full path and skip the lookup. Inside single quotes it is a TOML literal string, where backslashes need no escaping. toml [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](https://shuriken.sh/guides/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](https://shuriken.sh/guides/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](https://shuriken.sh/guides/codex-cli-mcp-servers), and the other config.toml keys are in our [config.toml guide](https://shuriken.sh/guides/codex-cli-config-toml). ## 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](https://shuriken.sh/features/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](https://shuriken.sh/download). Share [X](https://x.com/intent/post?url=https%3A%2F%2Fshuriken.sh%2Fguides%2Fcodex-mcp-server-failed-to-start&text=Codex%20MCP%20server%20failed%20to%20start%20or%20timed%20out%3A%20fixes)[LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fshuriken.sh%2Fguides%2Fcodex-mcp-server-failed-to-start)[Hacker News](https://news.ycombinator.com/submitlink?u=https%3A%2F%2Fshuriken.sh%2Fguides%2Fcodex-mcp-server-failed-to-start&t=Codex%20MCP%20server%20failed%20to%20start%20or%20timed%20out%3A%20fixes)[Reddit](https://www.reddit.com/submit?url=https%3A%2F%2Fshuriken.sh%2Fguides%2Fcodex-mcp-server-failed-to-start&title=Codex%20MCP%20server%20failed%20to%20start%20or%20timed%20out%3A%20fixes)[E-mail](mailto:?subject=Codex%20MCP%20server%20failed%20to%20start%20or%20timed%20out%3A%20fixes&body=https%3A%2F%2Fshuriken.sh%2Fguides%2Fcodex-mcp-server-failed-to-start) ## Sources - [OpenAI: Model Context Protocol in Codex (server options, timeouts, startup grace)](https://learn.chatgpt.com/docs/extend/mcp?surface=cli) (accessed 24 October 2026) - [Codex source, rust-v0.164.0: MCP startup error messages (codex-mcp/src/connection_manager/startup.rs)](https://github.com/openai/codex/blob/rust-v0.164.0/codex-rs/codex-mcp/src/connection_manager/startup.rs) (accessed 24 October 2026) - [Codex source, rust-v0.164.0: default startup and tool timeouts (codex-mcp/src/rmcp_client.rs)](https://github.com/openai/codex/blob/rust-v0.164.0/codex-rs/codex-mcp/src/rmcp_client.rs) (accessed 24 October 2026) - [Codex 0.118.0 release notes: longer startup window for local MCP servers (#16080)](https://github.com/openai/codex/releases/tag/rust-v0.118.0) (accessed 24 October 2026) - [Codex 0.141.0 release notes: default MCP tool timeout raised to 300 seconds (#28234)](https://github.com/openai/codex/releases/tag/rust-v0.141.0) (accessed 24 October 2026) - [Codex 0.151.0 release notes: configurable grace period for optional MCP servers (#41199)](https://github.com/openai/codex/releases/tag/rust-v0.151.0) (accessed 24 October 2026) - [Codex source: environment passed to local MCP servers (rmcp-client/src/utils.rs)](https://github.com/openai/codex/blob/rust-v0.164.0/codex-rs/rmcp-client/src/utils.rs) (accessed 24 October 2026) - [Codex source: Windows program lookup for MCP servers (rmcp-client/src/program_resolver.rs)](https://github.com/openai/codex/blob/rust-v0.164.0/codex-rs/rmcp-client/src/program_resolver.rs) (accessed 24 October 2026) - [GitHub issue 2945: MCP client for playwright failed to start: program not found](https://github.com/openai/codex/issues/2945) (accessed 24 October 2026) - [Model Context Protocol specification 2025-06-18: Transports (stdio)](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports) (accessed 24 October 2026) ## Frequently asked questions **What is the default MCP startup timeout in Codex?** 30 seconds in the Codex source since release 0.118.0 (31 March 2026). OpenAI's MCP page still says 10. Your own error message prints the timeout that was in force, so go by that. **Where do I put startup_timeout_sec?** In that server's own table in ~/.codex/config.toml, or in a trusted project's .codex/config.toml: startup_timeout_sec = 60 under [mcp_servers.context7], for example. The value is in seconds and covers that one server. **What does tool_timeout_sec do in Codex?** It caps one tool call; server startup has its own limit. OpenAI's page lists 60 seconds as the default, while the source has used 300 since release 0.141.0. A call that runs past it fails with timed out awaiting tools/call. **Why does Codex say program not found for an MCP server on Windows?** The server's command isn't on the PATH Codex handed it. Check with where.exe npx in the same terminal; install Node.js if it's missing and open a new terminal, or put the full path to npx.cmd in command. **Why does my MCP server work in a terminal but not in Codex?** Usually the environment. A local server gets a short list of variables from Codex, PATH and HOME among them, plus what you set in env and name in env_vars. An API key exported in your shell stays behind unless you name it. Global MCPs One MCP list for every agent. Add an MCP server once, choose its projects and sign in once. Your Claude Code, Codex and Gemini CLI chats all get it. [Download](https://shuriken.sh/download) [Other platforms](https://shuriken.sh/download#main) ## Keep reading - [Set up MCP servers once for every project: Guide 27 Oct 2026 5 min read Add an MCP server to every Claude Code project with user scope, how .mcp.json and ~/.claude.json differ, and how to keep Codex in step.](https://shuriken.sh/guides/mcp-servers-across-all-projects) - [Two Notion workspaces, one MCP list: Story 27 Oct 2026 3 min read Add Notion twice, once for work and once for personal, each with its own sign-in, and pick which projects get which. Switching accounts never asks again.](https://shuriken.sh/blog/two-notion-accounts-one-mcp-list) - [Claude Code MCP server timeout: the settings that fix it: Guide 27 Oct 2026 4 min read Claude Code MCP server timeout errors: the startup timeout for slow servers, a per-server limit for long tool calls, the idle window, and big output.](https://shuriken.sh/guides/claude-code-mcp-timeout) - [Claude Code across many projects: keep them apart: Guide 27 Oct 2026 6 min read Claude Code ties sessions, CLAUDE.md, settings and MCP servers to the folder you start it in. Run one session per project; put shared setup in user scope.](https://shuriken.sh/guides/claude-code-multiple-projects) - [Claude Code skills vs subagents vs MCP: which one to use: Guide 27 Oct 2026 6 min read Claude Code skills vs subagents: a skill is know-how in your chat, a subagent is work in its own context, MCP is a live outside system. One table to pick.](https://shuriken.sh/guides/claude-code-skills-vs-subagents) - [Migrate Claude Code to a new computer, settings and all: Guide 27 Oct 2026 8 min read To migrate Claude Code to another computer, copy ~/.claude without the login file, keep project paths the same so old chats resume, and sign in again.](https://shuriken.sh/guides/migrate-claude-code-to-new-computer) - [Set up Shuriken in your first hour: Guide 27 Oct 2026 5 min read Set up Shuriken in order: sign in, add a project, add your accounts and keys, choose when chats switch, add MCP servers once, then your phone and servers.](https://shuriken.sh/guides/set-up-shuriken) ## Free tools - [Claude limit reset tracker](https://shuriken.sh/tools/limit-resets/claude) - [Codex limit reset tracker](https://shuriken.sh/tools/limit-resets/codex)