codex - 💡(How to fix) Fix Add a bounded `codex mcp check <server>` diagnostic command for MCP startup and tool discovery failures

Problem

MCP failures are currently hard for users to report in an actionable way. Many issues include variants of:

• handshaking with MCP server failed: connection closed: initialize response
• server works when initialized manually, but fails when launched by Codex
• /mcp or the app/extension does not expose tools even though the configured server starts
• stderr/log output is difficult to capture in a concise, redacted support report

codex doctor --json already helps with install/config/auth/network/local-state diagnostics, and its MCP check catches important static problems such as missing commands, missing env vars, invalid cwd, and HTTP reachability. However, it intentionally does not start stdio MCP servers or perform a protocol-level startup/tool-discovery check.

That leaves a gap between:

• codex mcp list/get, which shows configured/effective MCP entries, and
• a full Codex session, which may fail with a generic startup or handshake error.

Evidence / related reports

Related examples include:

• #6020: broad initialize response startup failures with many comments
• #17024: local stdio server starts and manually initializes, but Codex startup fails
• #6465: MCP works in CLI but not in the VS Code extension
• #21903: Streamable HTTP MCP handshake failure after initialize
• #14242 / #16689: MCP server starts but tools are not discovered or exposed
• #7155: stderr-heavy MCP servers can fail on Windows
• #1454: older, closed request mentioning MCP debugging and hidden stderr

Proposal

Add a bounded diagnostic command, for example:

codex mcp check <server>
codex mcp check <server> --json

The command would inspect one configured MCP server and perform a safe protocol-level check without starting a full Codex session.

For stdio servers, the MVP could:

1. Resolve the effective config for <server>.
2. Validate the same local inputs already covered by doctor where possible.
3. Launch only that MCP server with a bounded startup timeout.
4. Send MCP initialize.
5. Send notifications/initialized.
6. Call tools/list.
7. Capture a small redacted stderr/stdout diagnostic excerpt.
8. Terminate the subprocess cleanly.
9. Report whether tools were discovered, how many, and where startup failed.

For Streamable HTTP servers, the command could start with the existing reachability probe and, if feasible, perform the equivalent bounded initialize/tools-list path.

MVP scope

• One server at a time.
• No MCP tool execution.
• No config mutation.
• No secret storage.
• No persistent MCP process.
• Human output plus --json.
• Redact paths/secrets consistently with codex doctor --json.
• Keep timeouts bounded and explicit.

Out of scope

• Lazy-loading MCP servers globally.
• Changing session startup behavior.
• Auto-repairing MCP config.
• Auto-approving MCP tool calls.
• Replacing codex doctor.

Expected impact

This would make MCP reports much more actionable for maintainers and easier for users to self-diagnose. It also gives the issue template a clearer instruction than “try prompting Codex to use the tool” when the problem is startup/tool discovery rather than tool behavior.

Risks / tradeoffs

• Starting arbitrary stdio MCP servers has side effects, so the command should be explicit, one-server-only, timeout-bounded, and clearly documented.
• Captured stderr must be small and redacted.
• Some servers may require auth or external state; the command should report that rather than trying to solve it.

Open questions

• Should this live under codex mcp check, codex mcp doctor, or as a codex doctor --mcp <server> mode?
• Should codex doctor --json include a hint recommending codex mcp check <server> when static MCP checks pass but a user reports startup failure?
• Should the JSON output reuse the DoctorCheck shape or have a separate MCP-specific report schema?