codex-app-mcp
This server is an MCP bridge that lets an MCP client (Claude, Cursor, etc.) start, steer, review, and manage persistent Codex CLI/app-server coding tasks over one connection.
Task orchestration: begin and loop through Codex sessions, manage goals, threads, and turns, and resume persisted work.
Status & diagnostics: probe connection status, run read-only app-server/account/config diagnostics, and discover models, features, permissions, MCP servers, plugins, skills, hooks, and account info.
Code review: run inline or detached reviews against uncommitted changes, branches, commits, or custom instructions.
File & command access: governed filesystem read/write/list/copy/remove under allowed roots, plus command/exec sessions and optional full-access process control.
Background jobs & scheduling: durable goal/turn jobs with SQLite ledger, plus timezone-aware RRULE schedules with retries and misfire policies.
Isolated worktrees (lanes): prepare, diff, run, poll, and review isolated git worktrees for parallel or experimental work.
Event handling: poll thread events, list pending approvals/inputs, respond to deferred requests, and manage approvals.
Protocol & RPC: inspect the versioned app-server JSON schema and call raw/read-only RPC methods, with unsafe stateful RPC gated behind operator allowlists and environment flags.
Admin & remote control: account actions, config management, plugin/skill management, memory, search, realtime, remote pairing, and Windows readiness operations.
MCP tool calls: invoke explicitly allowlisted downstream MCP/SaaS tools through the app-server.
Economy support: optional tokenBudget/economy controls to reduce host token usage.
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-mcp start a new thread to investigate the production outage"
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-mcp
Run and follow Codex coding tasks from your MCP client.
Start work, steer a task, review changes and return to persisted goals through one connection. The bridge connects your assistant to an installed Codex app-server; your Codex login and usage remain with Codex.
⚡ Host loop (Session v1.2)
Unofficial bridge. Save host tokens:
codex_app_session_begin({"goal":"…","host_budget":"small"})Loop
codex_app_session_next→ do onlycard(host_cmd|mcp_tool|end)Stop polling when
done=true, then finish withcodex_app_session_end.
Skill codex-mcp v1.0 enforces this. No OAuth in MCP config — CLI login only.
Claude / Cursor orchestrate → Codex app-server works (goals, budgets, policy roots).
Unofficial community project — not OpenAI, Codex, Anthropic, or xAI.
Auth = localcodex login(CODEX_HOME). Never put OAuth in MCP config or HTTP bearer.
Related MCP server: opencode-codex-mcp
Install (one command)
curl -fsSL https://raw.githubusercontent.com/zai-one/codex-mcp/main/scripts/install.sh \
| bash -s -- --project "$HOME/code/my-project"Windows: irm https://raw.githubusercontent.com/zai-one/codex-mcp/main/scripts/install.ps1 | iex
Then, on macOS/Linux:
codex login
source ~/.config/codex-mcp/env
~/.local/share/codex-mcp/.venv/bin/python ~/.local/share/codex-mcp/scripts/probe_stdio.pyMerge ~/.config/codex-mcp/mcp/claude_desktop.snippet.json → restart → codex_app_status.
On Windows, the installer writes %USERPROFILE%/.config/codex-mcp/env.ps1 and
installs the command into %LOCALAPPDATA%/codex-mcp/.venv/Scripts/.
Merge this entry into your MCP client, replacing both example paths:
{
"mcpServers": {
"codex": {
"command": "C:/Users/you/AppData/Local/codex-mcp/.venv/Scripts/codex-app-mcp.exe",
"env": {"CODEX_APP_MCP_ALLOWED_ROOTS": "C:/Users/you/code/my-project"}
}
}
}Restart the connection, then ask:
Show the Codex connection status, allowed project directories and available tasks. Do not start work yet.
Skill (router): codex-mcp — see docs/SKILLS.md
Full easy guide: docs/EASY.md
Language | Page |
Easy (canonical) | |
EN / RU / 中文 / ES | docs/install/ (short pointers) |
What it is
Host | Claude, Cursor, … (stdio or bearer HTTP) |
Worker | Codex CLI / app-server on same machine or VPS |
Why | Save host tokens under |
Economy |
|
Optional
Built by ZAI.ONE
ZAI.ONE is a digital agency working on websites, SEO, advertising and analytics. We also build tools that connect AI assistants to everyday work. Talk to us on Telegram about setup, automation or an integration for your team.
Found a bug or need a feature? Open an issue with a redacted reproduction. If the tool helps, give it a ⭐.
Available Tools
20 toolscodex_app_adminB
Typed access to account, config, apps/plugins/skills, environment, search, memory, realtime, and remote-control app-server operations. Mutations require the unsafe RPC operator gate.
Inputs: operation (required), params, timeoutSeconds, requireSupported.
codex_app_commandC
Run and control app-server command/exec sessions. Commands are argv arrays; danger-full-access remains an explicit governed option.
Inputs: action (required), cwd, env, tty, +13 more.
codex_app_discoverC
Discover live models/efforts, collaboration modes, features, permission profiles, configured MCP servers, apps, plugins, skills, hooks, or account.
Inputs: action (required), cwds, force, limit, +2 more.
codex_app_doctorA
Run read-only app-server, account, config-requirements, and Windows sandbox-readiness diagnostics without invoking codex doctor.
Inputs: no named parameters.
codex_app_eventsC
Poll cursor-paginated thread events, list pending approvals/input, or respond to a deferred app-server request.
Inputs: action (required), limit, cursor, answers, +7 more.
codex_app_fsC
Use app-server filesystem v2 for governed read/write/list/copy/remove/watch operations under allowlisted roots.
Inputs: action (required), path, text, force, +6 more.
codex_app_goalB
Start or manage a persisted autonomous goal. Activating a goal lets the Codex runtime generate continuation turns until terminal goal status.
Inputs: action (required), cwd, name, items, +30 more.
codex_app_jobC
Start, inspect, resume, or cancel durable background goal/turn jobs. Jobs use a SQLite ledger and expose persisted thread/turn identifiers.
Inputs: action (required), kind, jobId, limit, +3 more.
codex_app_laneC
Prepare/list/diff isolated codex/* git worktrees, run or background a turn, poll it, and review it through app-server.
Inputs: action (required), goal, lane, name, +22 more.
codex_app_mcp_callB
Call an explicitly allowlisted downstream MCP/SaaS tool through app-server. Disabled until server and tool allowlists are configured.
Inputs: tool (required), server (required), _meta, threadId, +1 more.
codex_app_processC
Control experimental unsandboxed app-server process/* sessions. Requires CODEX_APP_MCP_ALLOW_FULL_ACCESS=1.
Inputs: action (required), processHandle (required), cwd, env, +9 more.
codex_app_protocolC
Generate and inspect the exact versioned JSON schema exposed by the configured Codex app-server binary.
Inputs: action (required), kind, force, limit, +2 more.
codex_app_reviewA
Run the native app-server reviewer inline or detached against uncommitted changes, a base branch, a commit, or custom instructions.
Inputs: cwd, name, wait, items, +35 more.
codex_app_rpcA
Forward-compatible raw app-server RPC. Read methods use the built-in allowlist; stateful methods require an operator method allowlist plus CODEX_APP_MCP_ALLOW_UNSAFE_RPC=1.
Inputs: method (required), params, timeoutSeconds.
codex_app_rpc_readB
Version-forward-compatible escape hatch for a strict read-only RPC allowlist.
Inputs: method (required), params.
codex_app_runtimeA
Read gateway counters or explicitly restart the owned app-server connection. Restart requires the unsafe RPC operator gate.
Inputs: action (required).
codex_app_scheduleA
Create and operate durable timezone-aware RRULE schedules that launch Codex goal/turn jobs with idempotency, misfire policy, and retries.
Inputs: action (required), name, limit, rrule, +8 more.
codex_app_statusC
Start/probe the version-pinned Codex app-server connection.
Inputs: includeStderr.
codex_app_threadC
Create, list, read, resume, fork, name, compact, archive, unarchive, or unsubscribe persistent Codex threads.
Inputs: action (required), cwd, name, items, +27 more.
codex_app_turnC
Start, steer, or interrupt a turn on a loaded Codex thread.
Inputs: action (required), threadId (required), cwd, mode, +9 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Most tools have clearly distinct purposes (status, doctor, fs, events, etc.), but there is some overlap among job/lane/turn/goal management which could confuse agents about which to use for background work. Descriptions differentiate them, but boundaries are less crisp.
All tools follow a consistent codex_app_ prefix and mostly use noun-like names (status, doctor, fs, job), but a few use verbs (discover, mcp_call) and rpc_read is an adjective-noun combo. The pattern is predictable overall.
With 20 tools, this server is on the heavy side (16-25). The scope is broad enough that each tool may be justified, but the count will likely overwhelm agents and increase selection difficulty.
The tool surface is remarkably comprehensive, covering diagnostics, filesystem, events, jobs, scheduling, RPC, commands, threads, turns, goals, review, and process control. There are no obvious dead ends or missing core operations for the stated purpose of managing a Codex app-server.
Maintenance
Related MCP Connectors
A paid remote MCP for OpenAI Codex agent coordination MCP, built to return verdicts, receipts, usage
MCP Gateway: wrap any MCP server with cold-start retries, uptime SLA, and per-execution MPP billing.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Remote MCP server exposing SMI Aware tools, resources, and skills over Streamable HTTP.
Related MCP Servers
- AlicenseAqualityCmaintenanceA local MCP bridge that lets a compatible host start, monitor, steer, interrupt, resume, and approve Codex app-server work while enforcing repository-root security.10MIT
- FlicenseNot gradedqualityCmaintenanceEnables MCP-compatible hosts such as OpenCode to drive the Codex CLI through codex app-server over stdio, exposing tools to run prompts, inspect status, list threads, and interrupt running turns.-
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients and external AI supervisors to oversee and steer native Codex sessions through a thin local stdio bridge. It exposes eleven codex_* supervisory tools for tasks such as listing threads, starting turns, observing progress, steering, responding to approvals, interrupting, checkpointing, and rolling over work.MIT
- AlicenseAqualityCmaintenanceBridges MCP clients such as Claude Code and Cursor to independent Codex app-server sessions, letting them start, poll, steer, review, compact, cancel, and answer prompts for asynchronous Codex tasks over local stdio or a remote authenticated WebSocket. Runs read-only by default, with workspace-write sandboxing only when a user explicitly enables it, and reports job status, model listing, and progress back to the client.101MIT