Check the Codex app-server process, worker counts, and any unscoped pending server requests.

Dispatch a Codex worker: creates an independent thread and starts its first turn. Returns as soon as the turn is accepted; the worker keeps running in the background whether or not you watch it. Treat this like spawning a background subagent — issue several in one message to run a fleet, alongside any host-native subagents you also want, then go do other work and collect with agent_result. Do not follow this call with agent_wait. The prompt should be a complete, self-contained task including the acceptance criteria, since the worker cannot see your conversation. Common fields are provided directly; threadOptions and turnOptions pass additional app-server fields through, with direct fields taking precedence.

Load and subscribe to a persisted Codex thread after an MCP-server restart or from another Codex client.

Branch a managed agent or persisted Codex thread into a new independent worker. An optional prompt starts work immediately on the fork.

Send guidance to a worker. In auto mode this steers its active turn, or starts a follow-up turn when it is idle. Use an explicit mode when the distinction matters. Returns once the message is delivered, not once the worker has acted on it; poll agent_status afterwards rather than blocking on agent_wait.

Append guidance to the worker's current in-flight turn using turn/steer and its expected active turn id.

Interrupt a worker's active turn. Calling this on an idle worker is a no-op.

Detailed non-blocking snapshot of one worker: reduced current state, final or live message, plan, diff, usage, and pending approval/input requests. Use agent_result instead when you just want results or are checking more than one worker; reach for this when a single worker needs a closer look.

List every worker known to this MCP process, including Codex-created descendant agents discovered from the event stream. Returns immediately with one compact line per worker and no full messages. Use this to see the shape of the fleet, including workers Codex spawned on its own; use agent_result when you want their output.

Read a bounded page of reduced worker events after a cursor. Returns immediately. Data is omitted by default to avoid flooding the supervisor context. Use this for detail after agent_status shows something worth inspecting.

Block until watched workers are ready. This blocks your whole turn, so use it only once you have run out of other work — while you still have anything to do, dispatch it and poll with agent_result instead. Workers do not need this call to stay alive or make progress. When you do wait, always pass every outstanding worker in agentIds rather than waiting on one at a time: waiting serially multiplies the stall by the number of workers. Returns when the mode condition is met or the timeout expires, with a lean report for each ready worker and each one still running.

Collect worker results. Returns immediately with a lean report per worker: status, whether it is done, its final message, any approval it is blocked on, and its token spend. Call with no arguments to sweep every worker at once — this is the normal way to check on a fleet, and it costs one call no matter how many workers are running. Use this rather than agent_status unless you need one worker's plan, diff, or event detail.

Answer a pending app-server approval, permission, user-input, dynamic-tool, or MCP elicitation request. For command/file approvals, decision is shorthand for {decision}. For other request types, pass the exact response object shown by the current app-server schema.

Set or update the persistent app-server goal attached to a worker thread.

Archive an idle worker thread. Active turns must be interrupted first.