codex-local-mcp

Run parallel local Codex workers from any MCP client. Keep your regular Codex supervisor connected to its existing provider, and delegate bounded tasks to a LAN model through your codex-local launcher.

The server manages tasks and processes. Codex manages the tool loop. Your model service supplies inference; tools execute on the computer running the worker.

Features

• Four independent workers by default, with a configurable concurrency limit and bounded queue.

• Immediate submission responses, independent status queries, cancellation, execution deadlines, and explicit session continuation.

• Separate task IDs, Codex sessions, working directories, event logs, stderr, and final results.

• Atomic task metadata, bounded logs, idempotent submission, and recovery of stored results after restart.

• Official MCP TypeScript SDK, strict TypeScript, and stdio transport. No web server or separate daemon.

Related MCP server: Codex Control Plane MCP

Requirements and installation

Linux, Node.js 22+, and a working codex-local executable in PATH are required. codex-local must accept native Codex arguments and connect to your model service using the Responses API. Tested with Codex CLI 0.167.0. The server uses the provider ID lan_local for worker stream timeout configuration.

git clone https://github.com/gdrencn/codex-local-mcp.git
cd codex-local-mcp
npm ci
npm run build
node dist/cli.js --help

If you do not already have a launcher, see the optional shell example. It requires Codex, curl, jq, and Linux coreutils, discovers the current service model ID, and supplies generic text/image model metadata. It adds no custom CLI options. Keep the example beside its models.json file and either use its absolute path as CODEX_LOCAL_MCP_BINARY or add a symlink to it in PATH.

Connect to Codex

Choose the /v1 endpoint used by your launcher. Replace the endpoint and checkout location below with your own:

codex mcp add codex_local \
  --env CODEX_LOCAL_MCP_BASE_URL=http://127.0.0.1:8080/v1 \
  -- node /absolute/path/codex-local-mcp/dist/cli.js

Equivalent user configuration:

[mcp_servers.codex_local]
command = "node"
args = ["/absolute/path/codex-local-mcp/dist/cli.js"]

[mcp_servers.codex_local.env]
CODEX_LOCAL_MCP_BASE_URL = "http://127.0.0.1:8080/v1"

Keep the server ID codex_local, or set CODEX_LOCAL_MCP_SERVER_ID to the actual ID you register. Workers disable a complete inert entry under that ID to prevent recursive scheduling. The server does not edit your Codex configuration or login files automatically.

For an existing launcher, CODEX_LOCAL_MCP_BASE_URL controls the server's health check and must match the launcher's inference destination. The bundled example uses CODEX_LOCAL_BASE_URL, falling back to CODEX_LOCAL_MCP_BASE_URL, so one configured endpoint can serve both purposes.

Tools

Example submission:

{
  "prompt": "Read the parser and identify missing edge cases. Do not edit files. Cite relevant file paths.",
  "cwd": "/absolute/path/project",
  "request_id": "parser-review-1"
}

Use the returned task.id for queries. Pass each response's next_cursor on the next query; limit defaults to 50 and is at most 100. wait_ms can long-poll for up to 20 seconds. Errors are returned as MCP error results with a structured error.code and error.message.

Independent tasks run concurrently, including tasks waiting for inference or using tools. The model server may serialize its requests internally. Tasks above the concurrency limit queue. Turns continuing the same Codex session serialize without blocking unrelated sessions. For parallel modifications, provide separate worktrees or disjoint write scopes; this server does not create worktrees.

Sandbox defaults to read-only. Request workspace-write for an authorized modification task. Workers run with native approval mode never, disable external Apps/plugins, and pass prompts on stdin. These are worker invocation settings; your general codex-local command remains unchanged. images accepts up to 16 existing absolute local paths; the model service must support image input.

Request IDs deduplicate identical submissions, including after restart. Reusing an ID with different normalized input returns request_conflict. Whole agent tasks are never retried automatically, because a tool may already have changed files.

Configuration

A reachable nonempty /models response establishes reachability. Generation or tool failures still become failed tasks. The health request directly connects without using environment HTTP proxies. No alternative inference provider is selected on failure.

Task lifecycle and storage

States: queued, running, succeeded, failed, cancelled, timed_out, interrupted. Success requires exit zero and a completed Codex turn without a terminal failure. Failed individual shell commands can be recovered by the worker and do not automatically fail the entire task.

Each task has task.json, events.jsonl, stdout.jsonl, and stderr.log under <data-dir>/tasks/<task-id>/; empty output files need not exist. Prompts and tool outputs are local task data. Event summaries and returned final answers are bounded; raw log truncation is explicit. There is no automatic retention policy or global disk quota; remove old task directories while the server is stopped if necessary.

Normal client EOF, SIGINT, or SIGTERM stops owned workers. Cancellation targets the worker process group and a snapshot of descendants, including separately grouped tool children, with identity checks before escalation. This is process lifecycle management, not a security boundary beyond Codex's sandbox.

On restart, terminal results are restored and unfinished tasks become interrupted; work is not replayed. Live jobs are not guaranteed to survive a killed server or client disconnect. A second server must use a different data directory. A stale owner lock can be reclaimed when its PID is no longer alive; malformed locks fail explicitly rather than assuming the directory is safe to take over.

Development and verification

npm ci
npm run check
npm test
npm audit

Automated tests use a controlled worker and the official SDK client. They cover parallel starts, queueing, stream/argument boundaries, independent cancellation, detached descendants, timeouts, same-session continuation, recovery, bounded output, and protocol errors.

Opt-in real-service test:

CODEX_LOCAL_MCP_BASE_URL=http://127.0.0.1:8080/v1 npm run test:live

This checks two parallel local file-tool tasks, explicit session continuation, an authorized temporary workspace edit, and a generated image. It creates temporary fixtures and uses persistent Codex sessions for continuation. It does not modify the main Codex configuration. See IMPLEMENTED.md for observed results and limits.

Structure and provenance

src/domain.ts defines tasks; config.ts handles configuration; health.ts checks reachability; store.ts owns persistence; manager.ts schedules task lifecycles; codex.ts owns CLI arguments; output.ts decodes bounded JSONL; processes.ts owns Linux cleanup; server.ts adapts tools; cli.ts serves stdio.

The implementation is original. We reviewed denysvitali/codex-mcp, particularly explicit JSONL completion/failure handling and process groups, and ralphkrauss/agent-orchestrator, particularly independent worker lifecycles, cancellation, and durable results. No application code from either project is included. Protocol support comes from the official MCP TypeScript SDK. Original code is MIT licensed.