Multi-agent: cascading crash when MCP server referenced in skill docs doesn't exist

Open 💬 1 comment Opened Apr 2, 2026 by joeykrug

Summary

When Codex multi-agent mode is enabled (multi_agent = true), explorer and reviewer threads can crash the entire session if they attempt to use an MCP server that isn't configured in ~/.codex/mcp.json. The MCP errors themselves are non-fatal, but the cascading failure from a dead child process is not handled gracefully.

Reproduction

  1. Have multi_agent = true in ~/.codex/config.toml
  2. Have skills installed that reference MCP servers in their docs/examples (e.g., cpo-plugins-plugin-dev-mcp-integration references a filesystem MCP server in example configs)
  3. Do NOT configure those MCP servers in ~/.codex/mcp.json
  4. Run a task that triggers the explorer agent thread to read those skill files
  5. Explorer sees the MCP server reference, attempts to use it

Error Log

2026-04-02T16:01:53.546015Z ERROR codex_core::tools::router: error=write_stdin failed: Unknown process id 6193
2026-04-02T16:01:53.561974Z ERROR codex_core::tools::router: error=resources/read failed: unknown MCP server 'filesystem'
2026-04-02T16:01:53.561974Z ERROR codex_core::tools::router: error=resources/read failed: unknown MCP server 'filesystem'

Also saw: resources/list failed: unknown MCP server 'nonexistent' (from a test/example in the same skill).

Failure Cascade

  1. Explorer thread tries resources/list on MCP server nonexistent → ERROR
  2. Explorer thread tries resources/read on MCP server filesystem → ERROR
  3. These errors happen inside the child process handling the explorer's tool calls
  4. Child process (PID 6193) dies
  5. Parent orchestrator still has stdin pipe open to PID 6193, tries to write → write_stdin failed: Unknown process id 6193
  6. Orchestrator's tool router is now broken — can't communicate with explorer
  7. Session becomes unstable, eventually killed (signal 9)

Expected Behavior

  • Missing MCP server errors should be non-fatal — the thread should log the error and fall back to native file/shell tools
  • If a child thread process dies, the orchestrator should either:
  • Restart the thread
  • Continue without it (degrade gracefully)
  • At minimum, close the dead stdin pipe cleanly instead of repeatedly writing to it
  • write_stdin failed should not cascade into killing the entire multi-agent session

Workarounds Applied

  1. Added the @modelcontextprotocol/server-filesystem MCP server to ~/.codex/mcp.json (prevents the specific trigger)
  2. Added instructions to explorer/reviewer agent configs to only use configured MCP servers (prompt-level defense)

Environment

  • Codex CLI: 0.118.0
  • Config: sandbox.mode = "danger-full-access", multi_agent = true, agents.max_threads = 16
  • OS: Linux 6.12.67 (x64)
  • Only configured MCP server was wolfram

Impact

Any skill that references an MCP server name in its documentation can trigger this crash if the explorer thread reads that file and tries to use the referenced server. This makes multi-agent mode fragile in environments with many installed skills.

View original on GitHub ↗

This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗