Aident AI
Codex Says "MCP Startup Interrupted" but Servers Are Connected? Verify Before Reconfiguring
If Codex shows "MCP startup interrupted" but /mcp verbose lists the named server and a read-only tool call succeeds, the connection is healthy. Treat the startup banner as a status-reporting false positive. Do not delete the server, rotate credentials, or raise timeouts until a real connection check fails.
This distinction matters because recent Codex reports describe a Ready status event being dropped while the underlying MCP server remains usable. A second report describes a related case where a successful initialization is later shown as uninitialized. The warning is evidence to investigate, not proof that the transport failed.
What you need before testing
Have these ready:
The exact MCP server name from your Codex configuration.
A harmless read-only tool from that server, such as listing issues or reading documentation.
A terminal where you can run Codex CLI commands.
The current Codex version from
codex --version.
Do not paste bearer tokens, OAuth credentials, environment-variable values, or a complete config.toml into an issue or chat.
Step 1: Confirm the server is configured
Run:
Expected result: the affected server appears in the list and is enabled. This proves only that Codex has a configuration entry. It does not yet prove that initialization completed.
If the server is absent, this is a configuration problem rather than the false startup warning covered here. Follow the official MCP setup documentation before continuing.
Step 2: Check the live session state
Start Codex, then enter:
Expected result: the named server is active and its tools are visible. The official Codex command reference recommends /mcp for checking which servers and tools are available in the current session; verbose adds server diagnostics.
Classify what you see before changing anything:
| Read-only call | Meaning | Next move |
|---|---|---|---|
Server active, tools listed | Succeeds | Startup banner is stale or false | Keep the configuration and record the evidence |
Server active, tools listed | Fails | Initialization worked, but auth or tool execution failed | Diagnose the returned tool error |
Server missing or not initialized | Cannot run | Real startup or configuration failure | Check command, URL, auth, and server logs |
Server active, no tools listed | Cannot select a tool | Server returned no usable tool inventory | Inspect the server's initialization and |
Do not use the banner alone to choose a branch.
Step 3: Prove one harmless tool call
Ask Codex to run one named, read-only tool from the affected server. Be explicit about the action and its boundary. For example:
Expected result: Codex returns live data from that server. Record the server name, tool name, time, and outcome, but remove account identifiers and secrets.
If no clearly read-only tool exists, stop here. Do not use a write operation merely to test connectivity.
Why the warning can be wrong
In the August 1 Codex report, the local MCP server initialized in about 3 ms, /mcp showed connected tools, and calls worked even when the startup banner claimed interruption. The source analysis in that report traced the mismatch to a bounded in-process event channel:
Some startup status events are delivered on a best-effort path.
A busy consumer can miss the server's
Readyevent.The TUI sees a lag marker while its local status is still
Starting.The TUI labels that incomplete local view as interrupted even though the server is ready.
That analysis explains the reported reproduction, but it does not prove that every identical-looking warning has the same cause. The live server state and a harmless tool call are the discriminators.
Common wrong turns
Raising startup_timeout_sec immediately
The official default is 10 seconds, but the reported false positive reproduced with a 30-second timeout and a roughly 3 ms initialization. Increase the timeout only when logs show a genuinely slow server.
Removing and re-adding the server
If the server is active and a tool call works, reconfiguration adds risk without fixing the stale display state. It can also trigger unnecessary OAuth or credential changes.
Treating every failure as the same bug
MCP startup interrupted, server uninitialized, handshake timeout, tools/list failure, and tool-level authorization errors occur at different stages. Capture the exact stage that failed.
Testing with a write
Connectivity does not require creating an issue, sending a message, or modifying a record. Prefer schema inspection or a read-only list/get action.
If the server is actually unhealthy
When /mcp verbose does not show an active server, check the failure from the outside in:
Run
codex mcp listand confirm the intended entry is enabled.For a local STDIO server, run its executable with a safe help or version flag to confirm the command exists.
For a Streamable HTTP server, verify that the configured URL and authentication method match the official server instructions.
Check server logs for an initialization, transport, or OAuth error.
Change one variable at a time, then repeat
/mcp verboseand the same read-only call.
Do not publish full configuration files or raw logs until you have redacted secrets and personal data.
Report the false warning with useful evidence
A high-signal report should include:
Codex version and operating system.
STDIO or Streamable HTTP transport.
Exact warning text.
Whether
codex mcp listincludes the server.Whether
/mcp verboseshows it active and lists tools.The name and outcome of one read-only call.
Approximate initialization time, if available.
Reproduction frequency across clean launches.
This separates a dropped display event from a real server outage without exposing credentials.
Prefer brokered Actions when you do not need a local server
If your goal is to let an agent use an external API rather than develop or debug an MCP server, Aident Loadout can remove the local startup path entirely. It lets an agent search the capability catalog, inspect the exact input schema, preflight cost and risk, and execute through a connected Vault integration.
The measurable check is simple: complete one brokered read-only Action without copying a provider key into the project.
Follow the Aident setup instructions, then ask your agent to search for a read-only capability, inspect its schema, preflight it, and execute it with an explicit no-write boundary.
Sources
Source behavior and CLI commands were checked on August 4, 2026. Recheck the official documentation and issue status after a Codex update.
