Codex MCP tools not showing: checks and fixes
Find where the connection stops: server startup, handshake, tool visibility, or execution mode. Start with the symptom you can observe in the client you are using.
Start here
Run /mcp in the TUI (or open the desktop app's MCP UI) to see whether the server is listed as connected before assuming it failed to start.
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 no visible 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:
- The process never launched (or the config was rejected before launch).
- It launched but the handshake closed before
initializecompleted. - It connected but its tools were dropped —
/mcpshows the tools, the model does not get them. - 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.
After adding or authorizing a server
Once OAuth succeeds, let the login process finish and start a fresh session or restart the client as required. Do not repeatedly log in because an older task lacks the new tool catalog. If authorization is already waiting in the browser, complete that flow first. Then check the server status and one harmless read-only tool.
Quick checks
- Run
/mcpin the TUI (or open the desktop app’s MCP UI). Use the result to distinguish server visibility from whether an actual tool call succeeds. - Does a startup warning appear while
/mcpshows the server connected with its tools? If yes, you are in the false-warning branch, not a broken server. - Check the transport value in your
mcp_serversconfig — the two documented transports are STDIO (acommand) and Streamable HTTP (aurl). If configuration loading fails, compare the affected entry with the documentation for your installed client; the error alone does not identify the faulty field. - 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).
- 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. Compare the warning with the current server state and a safe read-only tool call. A connected label alone does not prove that every tool works. 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.tomlwithout backing it up first.codex mcp addand 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. compare the status display with a successful read-only tool call; the false-warning report names servers that were usable despite the banner.
- Separate configuration syntax from connection health. Use the supported command help and configuration reference; a server listing does not verify authentication, initialization and a usable tool call.
- 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 thecodex-mcp-startup-failedguide’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.
Evidence and limits
Official configuration keys were rechecked on the primary documentation host. The failure examples remain public reports, not reproductions by this site. A historical schema-conversion fix does not identify a currently affected release. Host-owned services can differ from user-configured MCP servers; a generic timeout value is not a guarantee for every integration.
This guide is part of our Codex mcp & configuration troubleshooting.
Compare another message in the Codex error guide library. First check whether this is a Codex service-side problem → View live Codex status.
Useful Codex tools
Sources
Each source lists what it is used to support. Sources are re-read on the review schedule, not continuously.
Codex MCP documentation (developers.openai.com)
MCP integration and client setup.
Codex configuration reference (developers.openai.com)
MCP command/url transport settings, tool filters, enabled/required flags and startup/tool timeout defaults.
Timeout then broken config loop (openai/codex #29396)
The verbatim 'timed out after 30 seconds. Add or adjust startup_timeout_sec', the 'invalid transport' config-load error, 'No MCP servers configured yet.', 'Error: No MCP server named 'codex_apps' found.', and the timeout-to-broken-config cycle.
False 'not initialized' warning (openai/codex #36486)
The verbatim 'MCP startup interrupted. The following servers were not initialized' banner naming servers that /mcp shows as connected and working, and that a reporter's root-cause analysis is source-reading, not a maintainer statement.
Desktop vs CLI host asymmetry (openai/codex #45555)
That Desktop shows the server in its MCP UI but exposes no tools while the CLI reports it connected, with verbatim lines 'status=starting', 'handshaking with MCP server failed:', and 'connection closed:', and that the Desktop-side root cause is stated as not known.
Silent omission on plugin stdio exit (openai/codex #42079)
That a plugin's stdio MCP process exiting before the initialize handshake makes Codex Desktop silently omit the server and its tools, and that the TUI converts failed-startup notifications into visible warnings while the Desktop app does not.
Connected but tools dropped on schema conversion (openai/codex #4176)
The verbatim 'Failed to convert ... MCP tool to OpenAI tool: Error("invalid type: map, expected a boolean")' and that this is a historical (codex-cli 0.40.0) mechanism, not a current defect; a fix commit is referenced but no shipped version is named.
Startup timeout not enforced (openai/codex #35551)
The verbatim 'Starting MCP servers (5/6): codex-security' stall where pressing Esc did not interrupt and the startup timeout did not fire for 23+ minutes.
Cloud execution: server absent (openai/codex #45640)
The verbatim 'resources/list failed: unknown MCP server 'youtube_transcript'' on cloud execution where the same server works locally, and the reporter's explicit statement that the cause was not diagnosed.
Related guides
How this page is checked
- Evidence level
- Reported - based on public reports, not reproduced here
- Last reviewed
- 2026-09-22
- Content updated
- 2026-09-22
- Full version scope
- Reported across codex-cli 0.40.0 through 0.154.0, the VS Code extension, and Codex Desktop, on macOS, Linux, WSL and cloud execution. Coverage is wide; no fix version can be named.
- Symptoms indexed
-
- You added an MCP server and restarted, but its tools are never available to the model
- The client prints a startup warning, yet /mcp later shows the server connected with its tools
- A server is silently absent from the task with no error shown
- The same config works in the CLI or IDE but not in the desktop app, or vice versa
Reviewer note
Current primary configuration reference checked on 2026-09-22. Issue reports remain conditional evidence; no universal fix or cross-client reproduction claimed.