Extension field notesUnofficial help

Last updated: ยท Applies to: Codex CLI, VS Code extension (including Remote-WSL) and desktop app MCP configuration

Codex MCP Setup and Errors: "failed to start", "timed out" Fixed

To fix Codex MCP startup errors, check the server command in config.toml, run its npx command once manually to cache the package, and set startup_timeout_sec = 60. On Windows, try cmd or an absolute path. For remote OAuth servers, run codex mcp login <name>, then verify with codex mcp list.

Codex MCP setup

Use ~/.codex/config.toml and a [mcp_servers.<name>] section; per-project configuration is also possible. See the official MCP documentation. Replace the package placeholder below with your server package.

[mcp_servers.example]
command = "npx"
args = ["-y", "<server-package>"]
startup_timeout_sec = 20
tool_timeout_sec = 45

startup_timeout_sec controls server startup; tool_timeout_sec controls tool calls. Both are in seconds. The values above are documentation examples.

Manage servers with these commands. Replace the name and package placeholders; use login/logout for OAuth servers and remove only when you intend to delete an entry. See the command definitions.

codex mcp add <name> -- npx -y <server-package>
codex mcp list
codex mcp get <name>
codex mcp login <name>
codex mcp logout <name>
codex mcp remove <name>

Codex MCP errors

Context7: request timed out

MCP client for `context7` failed to start: request timed out

Reported on Windows 11 with CLI 0.23.0 in issue #2555 and VS Code extension 0.5.15 with Remote-WSL in issue #4400. The latter also reports sentry, playwright and chrome-devtools. Try the startup timeout and package-cache steps below.

Context7: program not found

MCP client for `context7` failed to start: program not found

Issue #2555 reports this on Windows with command = "npx"; the user also tried command = "cmd" with args = ["/c", "npx", ...]. Try that command form or an absolute executable path; it is a troubleshooting step, not a guaranteed fix.

Generic server startup failure

MCP client for `{server_name}` failed to start: {error}

The pinned startup source formats the server name and underlying error this way. Use the underlying error to choose the command, timeout or authentication steps below.

Server timed out: adjust startup_timeout_sec

MCP client for `{server_name}` timed out after {N} seconds. Add or adjust `startup_timeout_sec` in your config.toml:
[mcp_servers.{server_key}]
startup_timeout_sec = XX

This is the template in the pinned timeout source. Set startup_timeout_sec = 60 under the affected server section.

MCP server is not logged in / requires OAuth reauthentication

The {server} MCP server is not logged in. Run `codex mcp login {server}`.

The pinned authentication source also includes the OAuth reauthentication variant:

The {server} MCP server requires OAuth reauthentication. Run `codex mcp login {server}`.

For remote/OAuth servers, run codex mcp login <name>.

Numbered fixes: CLI

  1. Check the configured command

    Inspect the affected entry with codex mcp get <name>. Run its npx command once manually to cache the package, replacing the package placeholder:

    npx -y <server-package>

  2. Allow more startup time

    Set this in the affected server section of config.toml:

    [mcp_servers.example]
startup_timeout_sec = 60

  3. Check Windows command resolution

    Try this Windows command form, or an absolute path to the executable. Keep the timeout in the same server section.

    [mcp_servers.example]
command = "cmd"
args = ["/c", "npx", "-y", "<server-package>"]
startup_timeout_sec = 60

  4. Authenticate and verify

    For a remote/OAuth server, log in, then check the configured servers:

    codex mcp login <name>
codex mcp list

Numbered fixes: VS Code, including Remote-WSL

  1. Check the server in the relevant environment

    In the terminal for the environment running Codex, including Remote-WSL when applicable, run codex mcp get <name> and the configured npx command once manually to cache the package.

  2. Adjust the server configuration

    Set startup_timeout_sec = 60 in the applicable config.toml. For a server launched on Windows, try the cmd example above or an absolute executable path.

  3. Authenticate and verify

    For remote/OAuth servers, run codex mcp login <name> in that environment. Verify with codex mcp list.

Numbered fixes: Desktop app

  1. Check the MCP entry

    Check the command in the app's applicable config.toml. Run its npx command once manually to cache the package.

  2. Apply the command or timeout fix

    Set startup_timeout_sec = 60 for the affected server. On Windows, try command = "cmd" with args = ["/c", "npx", ...] or an absolute executable path.

  3. Authenticate and verify

    For remote/OAuth servers, run codex mcp login <name> against the applicable configuration, then verify with codex mcp list.

FAQ

Where do I configure Codex MCP servers?

Use ~/.codex/config.toml with an [mcp_servers.<name>] section. Per-project configuration is also possible.

Which timeout should I change for MCP startup?

startup_timeout_sec controls server startup; tool_timeout_sec controls tool calls. Both are in seconds. Try startup_timeout_sec = 60 for startup timeouts.

How do I fix an MCP program not found error on Windows?

Try command = "cmd" with args beginning ["/c", "npx", ...], or use an absolute path to the executable.

How do I sign in to an OAuth MCP server?

Run codex mcp login <name> for the remote/OAuth server, then verify the configuration with codex mcp list.

Sources

This is an independent, unofficial help site. It is not affiliated with or endorsed by OpenAI. Check the linked documentation and reports for your environment.