Issue Station
Sign In
Tools hereToolbox

codex - ✅(Solved) Fix Stdio MCP servers can trigger terminal job-control suspension during startup on macOS [1 pull requests]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…

Root Cause

  • Interactive Codex startup can fail when specific stdio MCP servers are enabled.
    • The failure is confusing because it appears shell-related or MCP-specific rather than a Codex process-launch issue.
    • Optional MCP tools may silently disappear if users work around this by disabling servers.
    • Required MCP servers can block the entire session.

Fix Action

Fixed

PR fix notes

PR #1: Detach stdio MCP servers from the controlling TTY

Description (problem / solution / changelog)

Summary

Fixes openai/codex#18656.

Detach stdio MCP server processes from the controlling TTY before exec.

Today the stdio MCP spawn path assigns a new process group, but the child can remain attached to the terminal session. On macOS that can interact badly with shell job control if something in the server process tree touches the terminal, surfacing as zsh: suspended (tty input) during Codex startup.

This change makes stdio MCP children behave like other non-interactive helper processes already detached from the controlling TTY elsewhere in the codebase.

Why

stdio MCP servers are pipe-based helpers:

  • stdin/stdout are already redirected through pipes
  • interactive MCP flows are handled by Codex rather than by the server inheriting terminal ownership

Detaching them from the controlling TTY makes the launch model match that non-interactive design and avoids terminal job-control suspension.

Validation

  • just fmt
  • cargo test -p codex-rmcp-client --test process_group_cleanup -- --nocapture
  • cargo test -p codex-rmcp-client

The regression test covers the Unix stdio spawn path and asserts that the spawned server is detached from the controlling TTY/session.

Changed files

  • codex-rs/rmcp-client/src/rmcp_client.rs (modified, +18/-1)
  • codex-rs/rmcp-client/tests/process_group_cleanup.rs (modified, +119/-0)

Code Example

[mcp_servers.blitz-iphone]
     command = "npx"
     args = ["-y", "@blitzdev/iphone-mcp"]

---

zsh: suspended (tty input) codex ...
RAW_BUFFERClick to expand / collapse

What version of Codex CLI is running?

codex-cli 0.121.0

What subscription do you have?

Enterprise

Which model were you using?

gpt-5.4

What platform is your computer?

Darwin 25.4.0 arm64 arm

What terminal emulator and version are you using (if applicable)?

Ghostty, Terminal.app

What issue are you seeing?

On macOS, starting Codex with a stdio MCP server can result in terminal job-control failure during startup, observed as zsh: suspended (tty input).

After tracing this locally, the issue appears to be in how stdio MCP child processes are spawned: they are moved into a separate process group, but remain attached to the controlling terminal session. If anything in that server process tree touches the terminal, the shell can suspend it as a background TTY reader.

What steps can reproduce the bug?

Environment

  • Platform: macOS
  • Shell: zsh
  • Codex CLI: codex-cli 0.121.0
  • MCP transport: stdio
  • Example server that exposed the issue: npx -y @blitzdev/iphone-mcp
  1. Configure a stdio MCP server, for example:
     [mcp_servers.blitz-iphone]
     command = "npx"
     args = ["-y", "@blitzdev/iphone-mcp"]
  1. Start interactive Codex normally.
  2. During MCP startup, Codex may get suspended by the shell with:
     zsh: suspended (tty input) codex ...

What is the expected behavior?

Expected behavior

Codex should be able to start stdio MCP servers without exposing them to terminal job-control interactions. stdio MCP children are pipe-based helpers and should not depend on or inherit a controlling TTY.

Actual behavior

A stdio MCP child can remain in the terminal session while being placed in a separate process group. That creates a job-control hazard on macOS/zsh if the child process tree performs terminal I/O.

The visible user symptom is shell suspension during Codex startup rather than a clean MCP startup or a clean MCP failure.

Additional information

Impact

  • Interactive Codex startup can fail when specific stdio MCP servers are enabled.
  • The failure is confusing because it appears shell-related or MCP-specific rather than a Codex process-launch issue.
  • Optional MCP tools may silently disappear if users work around this by disabling servers.
  • Required MCP servers can block the entire session.

Why this seems like a Codex-side issue

From inspection, Codex already treats stdio MCP servers as non-interactive, pipe-based children. There is also already precedent in the codebase for detaching non-interactive child processes from the controlling TTY before exec. The risky behavior appears to be specific to the stdio MCP spawn path rather than a general requirement of MCP servers.

Proposed fix

In the stdio MCP spawn path, detach the child from the controlling TTY/session before exec rather than only assigning a new process group. That makes the child behave like a normal non-interactive helper process and avoids terminal job-control suspension. I have a candidate implementation plus a regression test in my fork: https://github.com/spqw/codex/pull/1

Validation

Locally, the candidate fix:

  • detaches stdio MCP children from the controlling TTY
  • preserves normal pipe-based stdio operation
  • passes crate tests including a focused regression test for detached-session behavior

Additional info

I’m happy to reshape the PR if you’d prefer this handled in a different layer, but I wanted to open the issue first since docs/contributing.md suggests discussing behavior changes before expecting a PR review.

extent analysis

TL;DR

Detaching the child process from the controlling TTY/session before exec in the stdio MCP spawn path may resolve the terminal job-control failure issue.

Guidance

  • Verify that the issue is specific to the stdio MCP spawn path and not a general requirement of MCP servers by testing with different MCP servers and configurations.
  • Detach the child process from the controlling TTY/session before exec, as proposed in the candidate fix, to prevent terminal job-control suspension.
  • Test the fix with a focused regression test for detached-session behavior to ensure normal pipe-based stdio operation is preserved.
  • Consider reshaping the PR if necessary, as suggested by the contributor, to handle the fix in a different layer.

Example

No code snippet is provided as the issue does not contain sufficient information to create a minimal example.

Notes

The proposed fix is specific to the stdio MCP spawn path and may not apply to other MCP servers or configurations. The contributor has already tested the candidate fix locally and reported positive results.

Recommendation

Apply the proposed workaround by detaching the child process from the controlling TTY/session before exec, as it has been tested and validated locally, and a regression test has been added to ensure the fix does not introduce new issues.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#ssr#chain error#conversation history#tool integration

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

codex - ✅(Solved) Fix Stdio MCP servers can trigger terminal job-control suspension during startup on macOS [1 pull requests]