›_ Codex Issues
Codex Issues / #36296

Codex Desktop: required MCP failure blocks task creation/resume with no recovery mode

Open 💬 0 comments Opened Jul 31, 2026 by jadeherzog

What version of the Codex App are you using (From “About Codex” dialog)?

26.721.81911

What subscription do you have?

ChatGPT Pro

What platform is your computer?

Microsoft Windows NT 10.0.26200.0 x64

What issue are you seeing?

A project-scoped local stdio MCP server was configured with enabled = true and required = true. When that server returned an error during initialize, Codex Desktop aborted the entire session: I could neither create a new task for the project nor resume an existing task.

Sanitized error:

Failed to resume chat
error resuming thread: Fatal error: Failed to initialize session:
required MCP servers failed to initialize:
<project-mcp>: handshaking with MCP server failed:
JSON-RPC error: -32602: Invalid params

This creates a recovery catch-22: the Codex task needed to inspect or repair the project cannot open because the project's MCP server needs repair. Desktop offered no safe recovery mode and no actionable protocol diagnostic.

Recovery required using a different project/task, querying Codex logs, manually replaying the JSON-RPC handshake, patching and rebuilding the server, then retrying Desktop. It took approximately one hour using Codex at Ultra reasoning effort. That is not a reasonable customer recovery path for one local integration error.

Important distinction: the immediate -32602 was caused by an overly strict validator in our custom MCP server, not by a malformed Codex request. We fixed that server bug and the task then resumed successfully. This report concerns Codex Desktop's recovery and diagnostic behavior after any required MCP initialization failure.

What steps can reproduce the bug?

  1. Configure a project-local stdio MCP server:
[mcp_servers.project-mcp]
command = "node"
args = ["dist/server.js"]
enabled = true
required = true
startup_timeout_sec = 30
  1. Have the server start but return a JSON-RPC error from initialize (for example, -32602 Invalid params).
  2. Try to create a Codex Desktop task for that project.
  3. Try to resume an existing task for that project.

Actual result: both operations fail before the task becomes usable. There is no visible retry/diagnostic workflow and no temporary recovery task that can open without the failed MCP.

The task resumed immediately after the MCP validator was fixed and rebuilt, confirming that required-MCP startup was the blocking gate.

What is the expected behavior?

Keep required = true fail-closed for ordinary MCP-dependent work, but provide an explicit recovery surface when initialization fails:

  1. A visible Retry MCP initialization action.
  2. A Copy redacted diagnostics action showing server name, startup phase, elapsed time, JSON-RPC error data, and bounded stderr.
  3. A user-confirmed, clearly degraded Open without this MCP for recovery mode that retains normal sandbox and approval controls.
  4. A bounded protocol diagnostic such as codex mcp check <server>, linked from the Desktop error.
  5. A persistent warning banner in degraded recovery sessions.

A required dependency may block dependent work, but it should not lock the customer out of the tools needed to diagnose that dependency.

Additional information

Environment:

  • Codex Desktop client/build: 26.721.81911
  • Installed Windows package observed: OpenAI.Codex_26.721.11231.0_x64
  • Bundled engine / MCP client: 0.146.0
  • MCP protocol: 2025-06-18
  • Transport: local stdio
  • Observed: 2026-07-31

Root-cause validation:

Codex sent standards-valid implementation information including:

{
  "protocolVersion": "2025-06-18",
  "capabilities": {},
  "clientInfo": {
    "name": "codex-mcp-client",
    "title": "Codex",
    "version": "0.146.0"
  }
}

Our validator incorrectly allowed only clientInfo.name and clientInfo.version, rejecting the optional title field defined by MCP. We added a regression test using this exact payload, rebuilt the server, verified the handshake, and confirmed the previously inaccessible task was active again.

MCP lifecycle specification:
https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle

Related issues (none appears to cover this exact Desktop recovery dead end):

  • #17143 — optional MCP startup could not be skipped in CLI/TUI:

https://github.com/openai/codex/issues/17143

  • #21318 — MCP startup/tool discovery on the startup critical path:

https://github.com/openai/codex/issues/21318

  • #24439 — proposal for a bounded codex mcp check <server> diagnostic:

https://github.com/openai/codex/issues/24439

  • #33403 — a different MCP defect that can prevent task creation:

https://github.com/openai/codex/issues/33403

Session identifiers and private local paths are intentionally omitted from this public report.

View original on GitHub ↗