Codex Desktop receives MCP startup failures but silently omits plugin tools

Codex Desktop receives MCP startup failure events but silently omits plugin tools

What version of the Codex App are you using?

26.825.51511 (build 7377), bundled codex-cli 0.151.0-alpha.7.2

What subscription do you have?

Authenticated ChatGPT subscription; the exact tier is not material to the reproduction.

What platform is your computer?

Darwin 27.0.0 arm64 arm

What issue are you seeing?

When an enabled local plugin's stdio MCP process exits before completing the initialize handshake, Codex Desktop silently omits that server and all of its tools from the task. The task UI does not show the launcher error, a failed-plugin state, or a recovery action.

In the reproduced case, the launcher wrote a stable diagnostic to stderr and exited. Local Codex logs then showed all of the following:

• the launcher stderr diagnostic was captured;
• mcpServer/startupStatus/updated notifications were emitted to connected app clients;
• the tool catalog omitted the server because there was no exact ready client;
• the task UI displayed none of this and the model received none of the plugin tools.

The current desktop bundle contains a handler that logs mcpServer/startupStatus/updated, including status, error, failureReason, threadId, and server name. The notification is therefore reaching the desktop boundary, but a generic failed plugin server does not become a durable, user-visible task warning.

This is distinct from a server that completes the handshake but whose tools are later filtered. The failure occurs before initialize, and Codex already has the failure information.

The reproduction does not depend on a specific private plugin: any minimal stdio MCP launcher that writes a diagnostic and exits before initialize should exercise the same boundary. No private plugin source, account data, or user content is required.

What steps can reproduce the bug?

1. Install and enable a local plugin with a stdio MCP server.
2. Make the plugin launcher print a stable error to stderr and exit non-zero before returning an MCP initialize response.
3. Start a fresh Codex Desktop task in a project where the plugin is enabled.
4. Observe the task UI and the model-visible tool list.
5. Inspect Codex logs.

Actual result:

• the plugin appears enabled;
• its tools are absent;
• the task UI shows no startup failure;
• logs contain the launcher stderr diagnostic and outgoing mcpServer/startupStatus/updated events;
• the tool catalog records that the server is omitted because no ready client exists.

What is the expected behavior?

Codex Desktop should retain and display a per-thread, per-server failed state whenever an enabled MCP server fails startup. The warning should include:

• plugin and server name;
• a bounded, sanitized error summary;
• classified failure reason when available;
• actions to retry startup and open diagnostics.

Tool omission should not be the only user-visible signal.

Additional information

The public app-server protocol already exposes the necessary notification:

• McpServerStatusUpdatedNotification includes thread_id, name, status, error, and failure_reason;
• the TUI already converts failed startup notifications into visible warnings;
• app-server integration coverage already verifies a failed optional stdio server produces mcpServer/startupStatus/updated with an error.

Relevant existing reports include:

• https://github.com/openai/codex/issues/4176 — silent exclusion after MCP tool conversion errors; closed by a schema-conversion fix, but it established that silent omission is harmful;
• https://github.com/openai/codex/issues/32447 — CLI visibly reports MCP startup failures, showing the expected failure-surfacing behavior;
• https://github.com/openai/codex/issues/34321 — an enabled plugin can contribute no capabilities while status remains apparently healthy.

Suggested implementation direction

Desktop renderer:

1. Subscribe to generic mcpServer/startupStatus/updated notifications for every server, not only special built-in servers.
2. Keep a state map keyed by (hostId, threadId, serverName).
3. On failed, render a deduplicated persistent warning in the affected task and invalidate the MCP status query.
4. On ready, clear the warning or mark it recovered.
5. Truncate and sanitize stderr-derived error text before display.

Public app-server follow-up suitable for a small PR:

1. Extend McpServerStatus with optional startup_error and startup_failure_reason fields.
2. Preserve the latest StartupOutcomeError in the read-only connection-status snapshot instead of collapsing it to the Failed enum alone.
3. Return those fields from mcpServer/list so clients can reconstruct the failed state after a reload or a missed notification.
4. Add an app-server integration test asserting that a broken optional stdio server is listed as failed with its bounded error text.

The renderer change is likely maintained outside the public openai/codex repository, but the persistent app-server status enhancement is independently PR-able and would make every client more robust.

Start with the public app-server entry points for McpServerStatus, StartupOutcomeError, mcpServer/list, and the mcpServer/startupStatus/updated notification; inspect the existing integration coverage for failed optional stdio servers. Trace how the read-only connection-status snapshot represents startup failures. Done means failed servers retain bounded error details in mcpServer/list and the integration test verifies them after startup failure.