Codex App Server MCP
An MCP server that makes Codex CLI a concurrent, steerable subagent pool inside an MCP host.
Start background Codex workers with agent_start, including model, cwd, sandbox/permissions, effort, output schema, and watchdog settings.
Dispatch native code review as a worker with agent_review, or hand off the host conversation with agent_handoff.
Resume persisted Codex threads with agent_resume and branch new workers with agent_fork.
Steer active turns with agent_steer, send follow-ups with agent_send, interrupt workers with agent_interrupt, and set persistent thread goals with agent_goal_set.
Collect lean results fleet-wide in one call with agent_result, inspect one worker deeply with agent_status, page through reduced events with agent_events, and block on any/all workers with agent_wait.
Answer pending approvals, permissions, user-input, dynamic-tool, or MCP elicitation requests via agent_request_resolve.
List all managed and discovered workers with agent_list, archive idle threads with agent_archive, and optionally expose raw_rpc for new app-server methods.
Includes optional worker watchdogs, Claude Code plugin integration, and a Pi extension for a codex_ subagent tool.
Provides tools for managing and coordinating multiple OpenAI Codex agents as a subagent pool, including starting, steering, inspecting, interrupting, resuming, and collecting results from Codex workers.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Codex App Server MCP Start two Codex agents to investigate this bug and propose fixes in parallel."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Codex App Server MCP
An MCP server that makes Codex a usable subagent pool inside an MCP host: a supervisor agent can create, coordinate, steer, inspect, and interrupt multiple Codex agents through the stateful Codex app-server protocol, and run them alongside the host's own subagents.
It works directly with MCP hosts such as Claude Code. A bundled Pi extension bridges the same MCP tools into Pi, whose core currently does not load MCP servers directly.
What it provides
Concurrent independent Codex threads through one long-lived app-server process
Non-blocking dispatch and fleet-wide collection, so supervising many workers costs one call
New, resumed, and forked workers
Protocol-level steering of active turns
Follow-up turns on completed workers
Bounded event history and reduced status instead of raw transcript flooding
Correlated command, file, permission, user-input, dynamic-tool, and MCP elicitation requests
Interruption, persistent goals, and archiving
Discovery of Codex-created descendant threads when the app-server event stream identifies them
An explicitly opt-in raw RPC escape hatch for new app-server methods
The implementation uses codex app-server, not codex exec.
Related MCP server: agentmux
Requirements
Node.js 24 or newer
A current Codex CLI available as
codexA working Codex login or configured model provider
Check the local setup:
node --version
codex --version
codex login statusInstall and build
git clone https://github.com/j-pollack/codex-app-server-mcp.git
cd codex-app-server-mcp
npm install
npm run buildThe MCP entry point is:
./dist/index.jsClaude Code setup
Add it as a user-scoped stdio MCP server:
claude mcp add --scope user codex-agents -- \
node "$(pwd)/dist/index.js"Run this command from the repository root. $(pwd) is expanded when the server is registered, so Claude Code stores an absolute path to your checkout.
For only the current project, use --scope local instead. Confirm it is present:
claude mcp listRestart Claude Code after adding the server. Its tools will be namespaced by the MCP server name in Claude's internal tool catalog.
Pi setup
Pi currently uses an extension for MCP integration. This package includes one and declares it in the package's pi.extensions manifest.
After building, install the local package:
pi install .Or try the adapter without installing it:
pi -e ./pi-extension/index.mjsRun either command from the repository root.
The adapter starts this MCP server, discovers its tools, and registers them in Pi with a codex_ prefix, such as codex_agent_start and codex_agent_wait. Run /codex-mcp in Pi to inspect the connection.
Subagents in Pi
Pi has no agent registry to add to, so a first-class subagent there is not a registered agent type but a tool that streams while it runs and draws itself. The extension registers one:
codex { task, cwd, mode: "task" | "handoff" | "review", label?, model?, sandbox? }
codex { cwd, tasks: [ { task, label }, ... ] }It dispatches the workers, tails them through the same agent_wait loop a relay agent would run,
and pushes every tick into the tool call's own display: a status icon per worker, its recent event
summaries, and its token spend, with the whole transcript and each final answer under the expanded
view (Ctrl+O). Several tasks run concurrently and stream side by side.
Aborting the call (Ctrl+C) interrupts the workers rather than leaving them running. Pi hands the
tool a real AbortSignal, so this is a direct agent_interrupt — none of the hook plumbing the
Claude Code plugin needs, and the server's watchdog stays as the backstop for the case where even
that fails.
codex blocks for the workers it starts, which is the Pi idiom and the opposite of the non-blocking
default elsewhere in this README. The raw codex_agent_start / codex_agent_wait tools are still
registered for the fleet style, where the point is to dispatch and keep working.
Codex as a second subagent pool
The design goal is that a supervisor can treat Codex workers the way it already treats its host's native subagents, and run both pools at the same time. Three properties make that work:
Dispatch is non-blocking.
agent_startreturns as soon as the turn is accepted. A worker needs no attention to keep running, so severalagent_startcalls can be issued in one message alongside whatever host-native subagents the supervisor also wants.Collection is fleet-wide.
agent_resultwith no arguments returns a lean report for every worker in a single call, so supervising ten workers costs the same as supervising one.Blocking, when it is needed at all, is also fleet-wide.
agent_waittakesagentIdswithmode: "any"ormode: "all", so a supervisor never serialises one wait per worker.
The loop
Dispatch. One message, several
agent_startcalls, plus any host-native subagents. Each prompt must be self-contained: the worker cannot see the supervisor's conversation.Work. Do supervisor work while the fleet runs. Nothing needs to be watched.
Collect.
agent_resultreturns{status, done, message, error, tokens}per worker, and surfaces any worker blocked on an approval.Only if idle, wait.
agent_wait({agentIds, mode: "any"})wakes on the first worker to finish so its result can be used while the rest continue.Zoom in when needed.
agent_statusfor one worker's plan and diff,agent_eventsfor its event history,agent_sendto steer or follow up,agent_interruptto stop redundant work.
Choosing what to send where
Codex workers are worth using where a different model is the point: an independent implementation pass to compare against, a second-opinion diagnosis, adversarial review of the supervisor's own work. Split the task so both pools run concurrently rather than in sequence.
An example request to the supervisor host:
Use Codex workers to investigate this failure. Start separate agents for the
runtime path, the test coverage, and a skeptical review. Let them run in
parallel, steer them if their scopes overlap, and synthesize their verified
findings. Do not approve destructive or externally visible actions.Codex workers as first-class subagents
An MCP server cannot register an agent type, so a Codex worker dispatched with agent_start renders
as a tool call in whichever transcript called it. The bundled Claude Code plugin in
plugin/ closes that gap the only way a host allows: a real host-native
subagent, codex-worker, that does nothing but drive one Codex worker and print its events. The
user gets a subagent row, an openable transcript, a /tasks entry, and an address they can message
— messages are forwarded to the worker with agent_send.
The cost is honest: the relay is a live model context that wakes on each tick to echo reduced events, so the transcript is a relay at up to 55-second granularity, not Codex's own stream. Pin it to a small model and forbid it from doing any thinking of its own.
The plugin also carries the hooks that stop a worker when the subagent driving it is interrupted. See Abandoned workers.
The repository root is a plugin marketplace, so installing it from a checkout is two commands:
claude plugin marketplace add "$(pwd)"
claude plugin install codex-agents@codex-app-server-mcpRestart Claude Code afterwards. The MCP server must be registered as codex-agents: the subagent's
tool list and the hook matchers both name mcp__codex-agents__*.
Abandoned workers
A worker keeps running whether or not anyone watches it, which is the point — and also a hazard
when the supervisor is interrupted mid-turn. Pass watchdogSeconds to agent_start to tie a
worker's life to its supervisor's attention: any agent_result, agent_wait, agent_status,
agent_events, or agent_send resets the window, and a worker nothing has read for a full window
is interrupted. One fleet-wide agent_result keeps a whole fleet alive.
Omit it and nothing changes: a worker with no watchdog is never interrupted for going unread, which is right for work meant to outlive the call that dispatched it.
Two faster signals feed the same mechanism. A host that interrupts a turn cancels the in-flight MCP
call, and agent_wait treats that cancellation as evidence its caller is gone. Host hooks, which
cannot call MCP tools, reach an interrupt-only unix socket at
~/.codex-app-server-mcp/servers/<pid>.sock. Neither is load-bearing on its own — hooks can be
absent and a killed host runs none — which is why the watchdog exists behind them.
Interrupting a turn leaves its thread log intact, so the work stays recoverable with agent_resume.
MCP tools
Tool | Purpose |
| App-server health, worker counts, and unscoped pending requests |
| Start a background worker and return without waiting for completion |
| Dispatch Codex's built-in reviewer against a diff, as a worker |
| Dispatch a worker that inherits the host's conversation |
| Load and subscribe to a persisted Codex thread |
| Branch a worker or raw thread into a new worker |
| Automatically steer an active worker or start its follow-up turn |
| Explicitly append guidance to an in-flight turn |
| Interrupt an active turn |
| Collect lean per-worker results for a fleet, or for every worker, in one call |
| Read one worker's detailed reduced state, plan, diff, and pending requests |
| List all managed and discovered workers |
| Page through bounded reduced events using a cursor |
| Block for up to 55 seconds awaiting one or all of a set of workers |
| Answer a correlated app-server request |
| Set or update a persistent thread goal |
| Archive an idle worker thread |
| Send arbitrary app-server RPC when explicitly enabled |
Native review
agent_review starts a worker whose first turn is Codex's own reviewer rather than a prompt. Codex
supplies the review instructions, which is worth more than asking a model to "review this diff", and
the result is an ordinary worker: same reduced state, same agent_result, same watchdog.
{ "scope": "base-branch", "baseBranch": "main", "cwd": "/abs/path/to/repo" }scope is uncommitted (the working tree, the default) or base-branch. The thread is read-only
unless threadOptions says otherwise, and delivery: "detached" runs the review on its own thread,
registered as a child worker. Reach for agent_start with a prompt instead whenever you want a
specific lens — adversarial review, one dimension, a design critique — since the native reviewer
takes no focus text.
Handing over a conversation
agent_start and agent_review both dispatch a worker that cannot see the supervisor's
conversation, which is why their prompts have to be self-contained. agent_handoff removes that
constraint: it imports a host agent's transcript into a Codex thread and starts the worker there, so
the worker reads the conversation first and the prompt is only what to do next.
{ "prompt": "Finish the migration we just designed.", "cwd": "/abs/path/to/repo" }With no sessionId or transcriptPath, the most recently written session for cwd is taken, which
on a live host is the running one. Detection is home-scoped and covers every project, so cwd is
what selects the conversation, not a search root.
The import is a real write: it creates a durable Codex thread, resumable from any Codex client, and
it stays after the worker finishes. Prefer agent_start when the task genuinely is self-contained —
a handoff costs an import and gives the worker the whole history, including the parts of it that
have since turned out to be wrong.
Advanced app-server options
agent_start exposes common settings directly: cwd, model, effort, serviceTier, personality, sandbox, permissions, approvalPolicy, approvalsReviewer, instruction overrides, workspace roots, thread config, an output schema, and watchdogSeconds.
agent_wait can also carry each worker's new events with includeEvents, paged from the cursor the wait itself used, so a supervisor tailing a worker spends one call per tick instead of a wait followed by agent_events.
Use threadOptions, turnOptions, resumeOptions, or forkOptions for fields introduced by newer app-server versions. The server always owns identity fields such as threadId, expected active turn IDs, and user input; callers cannot replace those invariants through an options object.
The installed Codex CLI can generate its exact protocol definitions:
npm run protocol:generateGenerated files go to the ignored .generated/app-server directory.
Approvals and server requests
App-server can stop a worker and request a client response. The MCP server records the request, marks the worker waiting, and returns a public requestId through agent_status or agent_wait.
For command and file approvals, decision is shorthand:
{
"requestId": "request-1-abcd1234",
"decision": "accept"
}For permission requests, user input, dynamic tools, and MCP elicitation, pass the response object required by the installed app-server schema:
{
"requestId": "request-2-efgh5678",
"response": {
"permissions": {},
"scope": "turn"
}
}The broker does not auto-approve. A supervisor can apply policy, but destructive actions, credentials, publication, deployments, and external communication should remain human decisions.
Concurrency and filesystem isolation
Concurrent threads are independent conversations, not isolated filesystems. Multiple write-capable workers pointed at the same checkout can overwrite or invalidate one another's work.
Prefer one of these arrangements:
one Git worktree per write-capable worker;
explicit non-overlapping file ownership;
several read-only investigators and one serialized writer.
Pass each worktree as cwd and, where appropriate, in runtimeWorkspaceRoots.
Environment variables
Variable | Default | Meaning |
|
| Codex executable path |
|
| JSON array of app-server process arguments |
| MCP process cwd | App-server process working directory |
|
| RPC request timeout for cancellable calls |
|
| RPC request timeout for |
|
| Initialize with experimental app-server APIs enabled |
|
| Per-worker reduced event retention |
|
| Maximum retained live/final text, diff, or event payload |
|
| Maximum supervisor-managed workers in one MCP process |
|
| Maximum simultaneously starting, running, or waiting workers |
|
| Expose the unrestricted |
|
| Default abandonment window for every worker; |
|
| Listen on the interrupt-only control socket |
|
| Directory holding control sockets and their registry files |
| current Node executable | Pi adapter override for starting this MCP server |
| built server entry | Pi adapter command arguments |
Example enabling the raw escape hatch in Claude Code:
claude mcp add --scope user -e CODEX_MCP_ENABLE_RAW_RPC=true codex-agents -- \
node "$(pwd)/dist/index.js"raw_rpc bypasses worker-registry invariants and can invoke destructive app-server methods. Leave it disabled unless you specifically need a protocol method that does not yet have a typed orchestration tool.
Persistence model
The MCP worker registry is in memory. Codex thread logs remain managed by app-server, so non-ephemeral threads survive an MCP process restart. Keep the returned threadId and use agent_resume to recover one.
Opaque agentId values are scoped to one MCP process and are not durable identifiers.
Development and verification
npm run check
npm run build
npm run smoke:real
npm run probe:protocolnpm run check is exactly what CI runs on Node 24, in the same order: formatting, lint, type checking over src, test, and scripts, then the fake app-server integration suite, an in-memory MCP client suite, and the spawned Pi adapter test. It needs no Codex binary, account, or network. npm install also points core.hooksPath at .githooks/. On commit, lint-staged formats and auto-fixes the staged files, then lint and types are verified across the project; on push, the suite runs. See CONTRIBUTING.md.
The other two scripts do talk to a locally installed Codex and spend real model usage, which is why CI excludes them. npm run smoke:real starts three simultaneous workers, waits on the fleet in one call, collects it in one more, and archives the threads at the end; it uses durable threads deliberately, because that is the shape whose abandoned turn can be cancelled by id. npm run probe:protocol re-checks the three live protocol facts the timeout-cancellation path relies on: that turn/start answers before it emits turn/started, that thread/turns/list still names the turn a timed-out call abandoned, and that turn/interrupt with an empty turnId stops a running turn without naming it.
The implementation was verified against Codex CLI 0.151.0 and @modelcontextprotocol/sdk 1.30.0, with three concurrent real worker turns.
Architecture
See Architecture. The app-server protocol itself is documented in the official OpenAI Codex App Server documentation.
License
MIT
Available Tools
15 toolsagent_archiveArchive Codex AgentADestructiveIdempotent
Archive an idle worker thread. Active turns must be interrupted first.
Inputs: agentId (required).
agent_eventsRead Codex Agent EventsARead-only
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.
Inputs: agentId (required), limit, afterCursor, includeData.
agent_forkFork Codex AgentA
Branch a managed agent or persisted Codex thread into a new independent worker. An optional prompt starts work immediately on the fork.
Inputs: label, prompt, forkOptions, turnOptions, +2 more.
agent_goal_setSet Codex Agent GoalCIdempotent
Set or update the persistent app-server goal attached to a worker thread.
Inputs: agentId (required), status, objective, tokenBudget.
agent_interruptInterrupt Codex AgentADestructiveIdempotent
Interrupt a worker's active turn. Calling this on an idle worker is a no-op.
Inputs: agentId (required).
agent_listList Codex AgentsARead-only
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.
Inputs: no named parameters.
agent_request_resolveResolve Codex Agent RequestA
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.
Inputs: requestId (required), decision, response.
agent_resultCollect Codex Agent ResultsARead-onlyIdempotent
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.
Inputs: agentId, agentIds, includeMessage.
agent_resumeResume Codex AgentBIdempotent
Load and subscribe to a persisted Codex thread after an MCP-server restart or from another Codex client.
Inputs: threadId (required), label, resumeOptions.
agent_sendSend to Codex AgentA
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.
Inputs: prompt (required), agentId (required), mode, turnOptions.
agent_startStart Codex AgentA
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.
Inputs: prompt (required), cwd, label, model, +15 more.
agent_statusInspect Codex AgentARead-only
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.
Inputs: agentId (required).
agent_steerSteer Active Codex AgentB
Append guidance to the worker's current in-flight turn using turn/steer and its expected active turn id.
Inputs: prompt (required), agentId (required).
agent_waitWait for Codex Agents (blocking)ARead-onlyIdempotent
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.
Inputs: mode, until, agentId, agentIds, +2 more.
server_infoCodex Orchestrator InfoARead-only
Check the Codex app-server process, worker counts, and any unscoped pending server requests.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
The tools cluster into clear lifecycle, control, and observation groups. The closest pairs—agent_send/agent_steer and agent_status/agent_result—have explicit usage guidance that distinguishes them, so an agent can usually select correctly.
The agent_ prefix is consistent, but the suffix style is mixed: most tools use imperative verbs (start, send, wait), while status, events, and result are nouns, and request_resolve/goal_set reverse the expected verb-noun order. server_info also breaks the agent_ naming pattern, though reasonably for a server-level tool.
Fifteen tools is on the higher end but fits the complexity of orchestrating background agent workers. Each tool covers a distinct lifecycle, observation, or control function, and none feels redundant or unnecessary.
The tool set covers the full agent lifecycle: start, resume, fork, guide, interrupt, observe, wait, collect results, resolve requests, set goals, and archive. There are no obvious dead ends, and every state change has a corresponding way to inspect or move forward.
Maintenance
Related MCP Connectors
- aXDeprecatedio.github.ax-platform
Agent-native collaboration network: orchestrate a team of long-running agents from any MCP client.
MCP-first control plane for ProAgentStore agents and private instances.
A paid remote MCP for OpenAI Codex agent coordination MCP, built to return verdicts, receipts, usage
Control plane for autonomous software labor. Agents claim objectives over MCP with audit trail.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables external AI supervisors to oversee and steer native Codex through MCP, including thread and turn management, observation, interruption, approval responses, runtime status, and checkpointing.MIT
- AlicenseBqualityBmaintenanceEnables any MCP host to delegate work to multiple coding-agent CLIs such as Codex, Claude Code, and Antigravity as subagents, preserving native sessions and supporting team-based supervision and agent-to-agent messaging.1711 npmApache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables MCP hosts to spawn, send input to, wait for, resume, and close provider-backed child agent sessions across Codex, Claude, and Grok adapters with configurable role presets, though it is experimental and not production-ready.MIT
- AlicenseBqualityBmaintenanceEnables a host coding agent to launch and coordinate real subagent sessions in other agent CLIs and accounts, sharing existing MCP servers, skills, plugins, and instructions. Supports two-way messaging, automatic account failover, and mixed-CLI delegation while leaving credentials with the vendor CLIs.813Apache 2.0