Codex MCP server added but its tools never appear

Find your next check

What you can see	Start with	What this tells you
No such file or directory (os error 2)	Check the server launch command	The configured executable may not be available to this client.
A warning, but tools are listed	Try a harmless read-only tool in the same client	A warning alone does not establish a broken connection.
Connected, but a tool is missing	Check tool allow and deny lists	Connection and tool availability are separate checks.
Handshake failed or connection closed	Read the server’s startup log	The connection ended before initialization completed.
Works locally but not in a cloud task	Compare execution mode and available configuration	A local result does not verify the cloud task.

Choose the matching branch below. Change one thing at a time, then repeat the same check in the same client.

What you see

One of these, or nothing at all:

⚠ MCP client for codex_apps timed out after 30 seconds. Add or adjust startup_timeout_sec in your config.toml:

⚠ MCP startup interrupted. The following servers were not initialized: …

handshaking with MCP server failed:
connection closed:

resources/list failed: unknown MCP server 'youtube_transcript'

Failed to convert "…" MCP tool to OpenAI tool: Error("invalid type: map, expected a boolean", line: 0, column: 0)

Or — and this is common — no error at all: the server is simply absent from the task. Note that MCP startup failed: and MCP startup incomplete (failed: belong to the launch-failure page this guide links to, not to this one; if your error is No such file or directory (os error 2), that page is the right one.

What it usually means

Adding a server and getting no tools is not one failure. The most useful first question is which of four things happened:

1. The process never launched (or the config was rejected before launch).
2. It launched but the handshake closed before initialize completed.
3. It connected but its tools were dropped — /mcp shows the tools, the model does not get them.
4. It never showed up for the execution mode you selected (e.g. cloud execution).

A separate, easy-to-misread case is the false warning: a banner says servers “were not initialized” while /mcp shows them connected and working. The documented way to resolve the ambiguity is /mcp — the official MCP docs state you use /mcp in the TUI to see your active MCP servers. The TUI and the desktop app do not surface this the same way (see the host-asymmetry branch), so the same config can look broken in one client and fine in another.

Quick checks

1. Run /mcp in the TUI (or open the desktop app’s MCP UI). Use the result to distinguish server visibility from whether an actual tool call succeeds.
2. Does a startup warning appear while /mcp shows the server connected with its tools? If yes, you are in the false-warning branch, not a broken server.
3. Check the transport value in your mcp_servers config — the two documented transports are STDIO (a command) and Streamable HTTP (a url). If configuration loading fails, compare the affected entry with the documentation for your installed client; the error alone does not identify the faulty field.
4. If you are on the desktop app, retry the same config through the CLI/TUI. A reporter found the CLI surfaced an error the desktop app swallowed (#42079).
5. Check the execution mode (local vs cloud) — #45640 is a cloud-only absence.

Fixes, by branch

If a startup warning appears but the tools actually work

#36486 reports the banner MCP startup interrupted. The following servers were not initialized: naming servers that /mcp then shows connected with their full tool list, and tool calls against them succeed. A reporter’s root-cause analysis (source reading, suggested) points at best-effort status events being dropped and a lag handler marking still-Starting servers as cancelled. Treat the banner as cosmetic until /mcp disagrees. This is not a fix you apply; it is a misread to avoid.

The documented required key makes startup fail if an enabled server cannot initialize — but a commenter on the same thread reported that setting required = true (with a higher startup_timeout_sec) did not eliminate the false warning. Present required as a documented lever with its documented meaning, never as a cure for a false warning.

If the config is rejected or the server never launches

#29396 shows a complete loop: a host-owned server times out at 30 s, the client prints a remediation, following it verbatim makes the config fail to load, and codex mcp list then reports No MCP servers configured yet. while codex mcp get codex_apps errors with Error: No MCP server named 'codex_apps' found. If you see Error loading config.toml: invalid transport, inspect the affected entry against the documentation before changing it. A stdio server uses a command; a Streamable HTTP server uses a url. Do not add a guessed transport field.

The documented startup timeout default is startup_timeout_sec = 10 (and tool_timeout_sec = 60). Note the documented 10 s default is not claimed to cover the host-owned server that was observed timing out at 30 s, so raising the value is reasonable but not guaranteed to match every server’s behaviour. Before editing config.toml, back the file up. The documented codex mcp add <server-name> --env VAR1=VALUE1 -- <stdio server-command> also writes to config.toml, so back up first there too.

If the process starts but the handshake closes

#45555 prints status=starting, then handshaking with MCP server failed: and connection closed:. In that report the same config and launcher passed the official SDK StdioClientTransport, passed through pnpm exec, and passed the Codex CLI (which reported openapi_to: connected (8 tools) via /mcp) — but Codex Desktop failed. The reporter explicitly states the Desktop-side root cause is not known. The takeaway is that the host matters: a server can be healthy in the CLI/IDE and broken in the desktop app, or vice versa.

If it connected but the tools were dropped

#4176 (codex-cli 0.40.0) reports /mcp listing the tools while the model receives none, with the stderr line Failed to convert "…" MCP tool to OpenAI tool: Error("invalid type: map, expected a boolean"). A fix commit is referenced, but no shipped version is named and this is presented as a historical mechanism (the shape of a connected-but-dropped server), not a current defect. If you see this conversion error in logs, it is a server-schema incompatibility, not a launch failure.

If the server is silently absent (desktop or plugin)

#42079 reports that when a plugin’s stdio MCP process exits before completing the initialize handshake, Codex Desktop silently omits that server and all its tools — no launcher error, no failed-plugin state, no recovery action in the task UI. The same report states the TUI already converts failed-startup notifications into visible warnings, so running the project through the CLI is a direct diagnostic lever: if the CLI shows a warning the desktop hid, that is your answer.

If you are on cloud execution

#45640 reports a server whose tools are unavailable under cloud execution while working locally, with resources/list failed: unknown MCP server 'youtube_transcript'. The reporter states the exact cause was not diagnosed and there is no maintainer reply. Present cloud execution as a scope to check (which execution mode is in play), not as a diagnosed cause.

The documented levers: timeouts, required, enabled, enabled_tools

The configuration reference documents these keys for an mcp_servers.<id> entry: startup_timeout_sec / startup_timeout_ms (startup timeout, documented default 10 s), tool_timeout_sec (per-tool timeout, default 60 s), required (fail startup/resume if this enabled server cannot initialize), enabled (disable without deleting), enabled_tools (allow list) and disabled_tools (deny list, applied after enabled_tools). A documented way to get a connected server that exposes zero tools to the model is an enabled_tools/disabled_tools configuration — worth checking before assuming the server failed.

What not to do

• Do not edit config.toml without backing it up first. codex mcp add and manual edits both write to that file; a bad edit can make the whole client fail to load (#29396).
• Do not assume a startup banner means the server is broken. /mcp is the source of truth; the false-warning branch shows banners that name healthy servers.
• Do not rely on a validation command. No command for validating an MCP configuration was found in the sources (codex mcp verify is not found, and codex mcp --help is documented but its output was not available). This guide deliberately publishes none.
• Do not name a version as fixed. The only fix reference found is a commit for #4176, with no shipped version, and the rest of these reports are open or unresolved.
• Do not confuse this page with the launch-failure page. If your error is No such file or directory (os error 2), that is the codex-mcp-startup-failed guide’s territory; this page explicitly excludes it.

How to tell it worked

You are done when /mcp shows the server connected with its full tool list and a real tool call against that server succeeds from the model. A listed tool still needs a successful read-only call to verify that it is usable. One clean /mcp reading is not enough if the failure is intermittent — give it a few tries across the clients you use.

If it is still failing

Collect: the client and version, the transport (stdio command vs streamable-HTTP url), which client (CLI, desktop, IDE) and which execution mode (local vs cloud), the /mcp output, and the exact warning or log line. Note whether the same config works in a different client — that asymmetry is itself diagnostic. If your error is os error 2, use the linked codex-mcp-startup-failed page instead.

Known limits of this guidance

• Evidence level: reported. Built from public GitHub issue reports and official documentation read via mirror; no reproduction was performed here.
• The canonical developers.openai.com/codex/mcp and /codex/config-reference pages returned HTTP 403 during research. Every official-doc claim above (the two transports, the key descriptions, /mcp, the defaults) is carried from mirrors and is not byte-verified against the canonical host.
• No documented way to validate an MCP configuration was found (codex mcp verify is not found; codex mcp --help is documented but its output was unavailable). No command that prints the config file path was found either.
• The relationship between the documented 10 s startup default and the observed 30 s host-owned timeout is unexplained; the docs’ default is not claimed to cover host-owned servers.
• No maintainer root cause was found for the silent-omission (#42079) or false-warning (#36486) classes — both are reporter-authored source reading, marked suggested.
• Whether required = true helps against the false warning is unresolved and there is evidence against it.
• No fix version can be named for any of these; #4176’s commit is referenced but its shipping version is unknown.
• Cloud execution (#45640) has no diagnosis — one report, no maintainer reply, cause explicitly unknown.
• The IDE menu path to config.toml is unresolved between the mirrors (“MCP settings” vs “Codex Settings”) and is not printed here.