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: AnyRouter Spawn Agent

Requirements

• Node.js 24 or newer

• A current Codex CLI available as codex

• A working Codex login or configured model provider

Check the local setup:

node --version
codex --version
codex login status

Install and build

git clone https://github.com/j-pollack/codex-app-server-mcp.git
cd codex-app-server-mcp
npm install
npm run build

The MCP entry point is:

./dist/index.js

Claude 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 list

Restart 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.mjs

Run 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.

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_start returns as soon as the turn is accepted. A worker needs no attention to keep running, so several agent_start calls can be issued in one message alongside whatever host-native subagents the supervisor also wants.

• Collection is fleet-wide. agent_result with 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_wait takes agentIds with mode: "any" or mode: "all", so a supervisor never serialises one wait per worker.

The loop

1. Dispatch. One message, several agent_start calls, plus any host-native subagents. Each prompt must be self-contained: the worker cannot see the supervisor's conversation.

2. Work. Do supervisor work while the fleet runs. Nothing needs to be watched.

3. Collect. agent_result returns {status, done, message, error, tokens} per worker, and surfaces any worker blocked on an approval.

4. 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.

5. Zoom in when needed. agent_status for one worker's plan and diff, agent_events for its event history, agent_send to steer or follow up, agent_interrupt to 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.

MCP tools

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, and an output schema.

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:generate

Generated 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

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:protocol

npm 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