codex-mcp
Turns a local OpenAI Codex CLI install into a persistent coding subagent that the main agent can delegate work to: starting tasks in a project, sending follow-ups, steering or interrupting turns, resuming conversations after a restart, polling progress events, exploiting native Codex features (subagents, plan mode, code review, forks, queues, history), running parallel tasks in Git worktrees, and handling approvals through a user prompt, an interactive review, or Codex's automatic reviewer, all inside a project-scoped sandbox.
Codex MCP
English | 简体中文
Let Claude Code (or another compatible MCP client) hand coding work to your local OpenAI Codex CLI, and keep a two-way conversation with it.
Codex MCP is a small local MCP server. It turns the Codex CLI on your computer into a persistent coding subagent for your main AI agent:
Persistent conversations. Start a task, send follow-ups, steer or interrupt it, and resume it after a restart.
Two-way communication. Codex can ask the main agent questions (
ask_parent), and the main agent answers them.Safe approvals. Nothing is approved silently. Approvals go to you, or to Codex's own automatic reviewer if you choose Approve for me.
Project-scoped sandbox. Codex's commands can change files only in the task's project folder, and they have no network access unless you approve it. Outside the project they can read only what programs need to run. See security.
Native Codex features. Subagents, plan mode, code review, forks, queues, history and more: 34 tools in total.
Parallel work and limits. Optional Git worktrees give parallel tasks their own checkout and hand back a reviewable patch; small plans start dependent steps in order; family budgets cap turns, time, tokens and stored output.
No extra dependencies. Uses only the Python standard library. Works on Windows, macOS and Linux, using local pipes and sockets only (never a network port).
Contents
Related MCP server: Codex MCP Server
Requirements
You need | Version | Check with |
Python | 3.11 or newer |
|
OpenAI Codex CLI | 0.167.0 or newer |
|
A Codex sign-in | ChatGPT account or API key |
|
An MCP client | Claude Code, Claude Desktop, or another stdio client |
Codex's own sandbox must work on your computer. The bridge never turns it off. On Windows, Codex's legacy unelevated sandbox is not supported; use the sandbox mode Codex sets up by default (see installation details).
Installation
The steps below use Claude Code. For other clients, see Step 5 and docs/installation.md.
Step 1: Install Python
Windows: Install Python 3.11+ from python.org. In the installer, tick Add python.exe to PATH. This also installs the
pylauncher used below.macOS:
brew install python, or use the installer from python.org.Linux: Use your distribution's package, for example
sudo apt install python3.
Step 2: Install and sign in to Codex
npm install -g @openai/codex
codex loginAny official installation method works. See OpenAI's Codex CLI guide. Then check:
codex --version
codex login statusThe version must be 0.167.0 or newer. Run codex update to upgrade an older installation.
Step 3: Download Codex MCP
Get the code from the codex-mcp repository and keep the folder in a permanent location (for example ~/tools/codex-mcp or C:\Tools\codex-mcp), because your MCP client runs the server from there. The repository is public, so you don't need a GitHub account.
Git:
git clone https://github.com/houyhlouis/codex-mcp.git cd codex-mcpGitHub Desktop: Choose File → Clone repository, open the URL tab, enter
https://github.com/houyhlouis/codex-mcp, choose a local path, and click Clone.ZIP: On the latest release page, download Source code (zip) and extract it. Rename the extracted folder to
codex-mcp.
Nothing needs to be installed after downloading: the server runs straight from this folder. If you would rather have a codex-local-mcp command, see installing as a Python package.
Step 4: Check that it works
Run these commands in the codex-mcp folder.
macOS / Linux:
python3 server.py --version
python3 server.py statusWindows (PowerShell):
py -3 server.py --version
py -3 server.py statusstatus starts the background broker and Codex, then prints JSON that should include "signed_in": true. It does not run a model or use any quota. The broker keeps running in the background and is started again automatically when it is needed.
Step 5: Connect your MCP client
Claude Code. Run this inside the codex-mcp folder.
macOS / Linux:
claude mcp add --transport stdio --scope user codex -- python3 "$PWD/server.py" serveWindows (PowerShell):
claude mcp add --transport stdio --scope user codex -- py -3 "$PWD\server.py" serve--scope user makes the server available in all your projects. Leave it out to add it to the current project only. Check the connection with claude mcp list, or type /mcp inside Claude Code. codex should show as connected.
Claude Desktop and other clients. Add this to the client's MCP configuration file (for Claude Desktop: Settings → Developer → Edit Config), then restart the client:
{
"mcpServers": {
"codex": {
"command": "python3",
"args": ["/absolute/path/to/codex-mcp/server.py", "serve"]
}
}
}On Windows use "command": "py" and "args": ["-3", "C:\\Tools\\codex-mcp\\server.py", "serve"]. Ready-made files: examples/mcp.json and examples/mcp.windows.json.
Step 6 (optional): Teach your agent the workflow
Copy examples/CLAUDE.md into your project's CLAUDE.md (or your agent's instructions file). It explains how to poll for progress, answer questions and treat approvals.
No configuration file is needed. Optional settings, such as a custom Codex path or concurrency limit, are described in docs/configuration.md.
Your first task
Ask your main agent in plain language:
Use Codex in this project to find out why the tests fail and fix them.
Keep me updated and answer any questions it asks.Create a new project folder ~/projects/todo-cli and ask Codex to build a small
command-line to-do app with tests. Use "Approve for me" for this task.Continue the same Codex conversation: add a --json flag and run the tests again.Behind the scenes, the main agent selects a project with codex_projects, starts work with codex_start, and polls codex_events until the turn finishes. It answers Codex's questions with codex_respond and reads the result with codex_get. See the usage guide for the full workflow and more examples.
Approvals
Codex asks for approval before actions outside its sandbox, such as running a command that needs network access. You choose who decides for each task with approval_mode:
Mode | Who decides |
| Whatever your Codex configuration already uses |
| You. The request is shown as a prompt in your MCP client, or you review it in a terminal |
| Codex's built-in automatic reviewer. It can approve or deny; the sandbox stays on |
The main agent can always deny a request, but it cannot approve one on your behalf unless you explicitly enable approval_relay in the configuration. If your client cannot show prompts, review the request in a terminal:
python3 server.py review REQUEST_IDUpdating and uninstalling
Update:
cd codex-mcp
python3 server.py stop
git pullThen restart your MCP client. (Windows: py -3 server.py stop.) Always stop the broker before you update, so that the old broker never loads a file from the new version. Otherwise the client also reports that a broker from a different version is still running. Stop it when no task is working: a task that is interrupted by the stop keeps its project reserved until you call codex_resume for it.
If you installed from a ZIP, run python3 server.py stop first, then replace the folder with the new Source code (zip) from Releases.
Uninstall:
python3 server.py stopclaude mcp remove codex --scope user(or remove the entry from your client's configuration)Delete the
codex-mcpfolder.Optionally delete the saved task history:
~/.local/state/codex-mcpon macOS/Linux,%LOCALAPPDATA%\CodexMCPon Windows.
Troubleshooting
Problem | What to do |
Anything unclear | Run |
| Make sure |
| Check the path in your client's configuration and run the same command by hand, for example |
A broker from a different version or configuration is running | Run |
A task is stuck in | It is waiting for an answer or approval. Ask the main agent to list pending requests, or run |
Something else | See docs/troubleshooting.md. The private log is |
How it works
flowchart LR
A[Main agent<br/>e.g. Claude Code] <-->|MCP over stdio| B[server.py serve]
B <-->|private local socket / pipe| C[Background broker]
C <-->|app-server protocol| D[Codex CLI]
D --> E[Your project]The MCP server that your client starts is a thin adapter. A background broker owns the Codex connection, stores tasks and events in a private SQLite database, and keeps running when the client disconnects. A reconnecting client can catch up from where it left off. See architecture and security.
The sandbox applies to the commands Codex runs, not to Codex itself: the Codex process still uses your sign-in and the network to reach the model. Security lists exactly what commands can read and change.
Documentation
Guide | What it covers |
Other MCP clients, package install, Windows notes, running the broker manually | |
The task workflow, approvals, subagents, plan mode, forks, queues, recovery | |
All 34 tools, their arguments, task states and response formats | |
Optional settings file | |
Common errors and how to fix them | |
Trust model, sandbox, approvals and stored data | |
Components, message flow and delivery guarantees | |
What is intentionally not supported, and workarounds | |
Tests, CI, live checks and release packaging | |
Release notes |
Development
python3 -m unittest discover -vThe offline suite uses a simulated Codex process and uses no model quota. CI runs it on Windows, macOS and Linux with Python 3.11 and 3.14 after every push. See docs/development.md and CONTRIBUTING.md.
License
Available Tools
34 toolscodex_archiveADestructive
Archive or restore an idle conversation and its native descendants. Transcripts are retained.
Inputs: task_id (required), action, request_id, operation_id. Returns: ok, result_version
codex_capabilitiesCRead-onlyIdempotent
Discover native collaboration/permission options and direct-input capability for a task.
Inputs: task_id (required). Returns: ok, result_version
codex_compactADestructive
Request native history compaction for an idle conversation; may consume model usage. Poll completion events.
Inputs: task_id (required), request_id, operation_id. Returns: ok, result_version
codex_delegateBDestructive
Ask a parent to manage native subagents; discover them with codex_subagents. Active parents require expected_turn_id.
Inputs: prompt (required), task_id (required), contract, request_id, +2 more. Returns: ok, result_version
codex_deleteADestructive
Permanently delete an owned native conversation and descendants. Requires the exact native thread_id in confirm_thread_id and an idle family. Local bridge audit records remain.
Inputs: task_id (required), confirm_thread_id (required), request_id, operation_id. Returns: ok, result_version
codex_diffARead-onlyIdempotent
Retrieve the current native turn's diff and reported file changes; old diffs are not carried into new turns. Does not invoke Git hooks or execute a shell.
Inputs: task_id (required). Returns: ok, result_version
codex_eventsBRead-onlyIdempotent
Replay progress or wait up to 25s. Drain has_more. For fragments, keep after and use event_seq/next_event_offset until complete. Page requests with requests_cursor. outcome coalesces state for task_ids (max 50); return cursors unchanged on the next poll. Detailed replay uses after separately.
Inputs: view, after, limit, cursors, +9 more. Returns: ok, result_version
codex_forkADestructive
Fork an idle owned conversation, optionally through a selected turn. Keeps project boundaries; does not start work or automatically continue a goal.
Inputs: task_id (required), name, request_id, last_turn_id, +1 more. Returns: ok, result_version
codex_getCRead-onlyIdempotent
Read task state and cumulative usage. workspace_claims explain ownership; page requests, children and claims. Large fields identify truncated_fields. result pages turn evidence (pin result_id); artifact reads scoped bytes by artifact_id. Use offset/limit. reconciliation explains recovery; permissions pages receipts and scope.
Inputs: task_id (required), view, limit, offset, +9 more. Returns: ok, result_version
codex_goalADestructive
get reads a goal; set takes objective/status/token_budget; clear removes it. Mutations need user_requested=true and an operation key. Only change goals on explicit human instruction.
Inputs: task_id (required), action, status, objective, +4 more. Returns: ok, result_version
codex_historyBRead-onlyIdempotent
Page persisted turns or items for owned conversations, including after an outage. Large items identify truncated_fields; pending approval details come from codex_review_request.
Inputs: task_id (required), kind, limit, cursor, +1 more. Returns: ok, result_version
codex_interruptADestructive
Ask Codex to interrupt the specified active turn. Poll for interrupted/completed; interrupt acknowledgement alone is not completion.
Inputs: task_id (required), expected_turn_id (required), request_id, operation_id. Returns: ok, result_version
codex_listBRead-onlyIdempotent
Page persistent tasks, newest first. Large projections identify truncated_fields.
Inputs: view, limit, offset. Returns: ok, result_version
codex_modelsBRead-onlyIdempotent
Discover model ids, supported reasoning efforts and defaults. Catalog visibility is not an entitlement guarantee.
Inputs: limit, cursor. Returns: ok, result_version
codex_plansADestructive
submit: spec/key; inspect: plan_id; list: offset/limit; cancel: plan_id/key. Runs bounded dependency plans through ordinary task admission. Unknown outcomes wait for explicit resume; no side effect is retried.
Inputs: action (required), spec, limit, offset, +3 more. Returns: ok, result_version
codex_projectsBDestructive
List selected projects with offset/limit; select/create takes path. The main agent chooses an absolute project directory.
Inputs: path, limit, action, offset. Returns: ok, result_version
codex_queueCDestructive
list takes cursor/limit; add takes prompt and optional images/context_files/skills; update also needs queued_id; delete needs queued_id; reorder needs ordered_ids; start takes optional queued_id. Mutations need an operation key.
Inputs: task_id (required), limit, action, cursor, +8 more. Returns: ok, result_version
codex_renameCDestructive
Rename an owned native conversation.
Inputs: name (required), task_id (required), request_id, operation_id. Returns: ok, result_version
codex_requestsARead-onlyIdempotent
Page bounded pending approval/question summaries using cursor. Fetch complete content by id with codex_review_request before approval. Never infer approval from silence or timeout.
Inputs: limit, cursor, task_id. Returns: ok, result_version
codex_respondADestructive
Answer guidance or review requests. Typed decisions apply only to ask_parent. Approvals need human/relay; file accepts need proposal_hash. Denials need no human.
Inputs: response (required), request_id, proposal_hash, pending_request_id. Returns: ok, result_version
codex_resumeBDestructive
Reconcile native history and execution intent after reconnect. No prompt or command replay. Inspect codex_history before a follow-up.
Inputs: task_id (required), request_id, operation_id. Returns: ok, result_version
codex_revertADestructive
Remove a selected turn and all later native conversation history. DOES NOT revert files. Requires explicit acknowledgement; local event audit remains.
Inputs: task_id (required), before_turn_id (required), confirm_history_only (required), request_id, +1 more. Returns: ok, result_version
codex_reviewBDestructive
Start native code review of uncommitted changes, a base branch, a commit or custom instructions on an idle task. Poll for findings/results.
Inputs: task_id (required), branch, commit, target, +3 more. Returns: ok, result_version
codex_review_requestCDestructive
Human review, or read details with offset=0. Follow next_offset and verify detail_sha256. Acceptance requires complete content.
Inputs: limit, offset, request_id, pending_request_id. Returns: ok, result_version
codex_sendBDestructive
Send a follow-up turn or steer active work. Steering needs the current expected_turn_id; follow-ups can select a supported model/effort.
Inputs: prompt (required), task_id (required), mode, model, +8 more. Returns: ok, result_version
codex_sessionsCDestructive
Choose workdir or project_id. list takes cursor/limit/archived; import takes thread_id, confirm_stopped=true, optional archived and an operation key. Native scope is verified before work.
Inputs: limit, action, cursor, workdir, +6 more. Returns: ok, result_version
codex_settingsADestructive
get reads settings. next takes model/effort/approval_mode/collaboration_mode/service_tier/access and root-only family budget (applies now; {} clears). current takes model/effort/approval_mode/service_tier and expected_turn_id. Changes need an operation key.
Inputs: task_id (required), model, scope, access, +8 more. Returns: ok, result_version
codex_skillsBRead-onlyIdempotent
List native skills available for this project. Select enabled skills by name in start/send; no global skill configuration changes.
Inputs: task_id (required), force_reload. Returns: ok, result_version
codex_startBDestructive
Start a persistent Codex conversation and return promptly with a task id. Poll codex_events and handle pending_requests until the turn finishes.
Inputs: prompt (required), name, model, access, +12 more. Returns: ok, result_version
codex_statusBRead-onlyIdempotent
Check installed Codex, sign-in type, pending request summaries and broker health.
Inputs: requests_limit, requests_cursor. Returns: ok, result_version
codex_subagentsCRead-onlyIdempotent
Page verified descendants; parent events include child requests. refresh=false uses offset; refresh=true uses cursor. Respect can_accept_direct_input.
Inputs: task_id (required), limit, cursor, offset, +2 more. Returns: ok, result_version
codex_terminalsBDestructive
list takes cursor/limit; terminate takes process_id; clean stops all background terminals. Mutations need an operation key. No arbitrary shell or stdin.
Inputs: task_id (required), limit, action, cursor, +3 more. Returns: ok, result_version
codex_usageARead-onlyIdempotent
Read native account rate limits/remaining allowance. Does not buy credits or change billing.
Inputs: no named parameters. Returns: ok, result_version
codex_worktreesBDestructive
plan/create: repo or project_id, name, optional base; create also plan_id/key. inspect: project_id or path, offset/limit. handoff: finished task_id. cleanup: project_id, optional keep_branch, key. Except inspect, needs worktrees=true. Never merges/pushes.
Inputs: action (required), base, name, path, +9 more. Returns: ok, result_version
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 34 tools
Most tools map to distinct Codex lifecycle operations, but several boundaries are subtle: codex_review vs codex_review_request, codex_requests vs codex_respond, and codex_events vs codex_history can easily be confused. The dense descriptions help, but the agent must parse a lot to choose correctly.
All tools use a consistent codex_ snake_case prefix, but the suffix style mixes verbs, nouns, and plural resource containers (codex_start, codex_get, codex_plans, codex_settings, codex_subagents). This is readable but not a predictable verb_noun convention.
34 tools is heavy for an agent-facing server and exceeds the reasonable range for smooth tool selection. The broad Codex lifecycle may justify many operations, but the surface feels overgrown and should likely be consolidated.
The surface covers conversation creation, resume, listing, inspection, events, history, approvals, settings, worktrees, subagents, queueing, review, deletion, and project/session handling. No obvious lifecycle gap stands out for a Codex task-management server.
Maintenance
Related MCP Connectors
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Connect ChatGPT and Claude to your Mac, Windows or Linux with secure MCP remote access.
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
MCP hosting for AI agents: Claude or Codex writes the code, runs it and sends a live link.
Related MCP Servers
- AlicenseAqualityFmaintenanceCall OpenAI Codex from Claude Code for independent second opinions, structured code review, and delegated coding tasks through a FastMCP plugin that drives the codex CLI safely.17325 PyPI3MIT
- AlicenseNot gradedqualityDmaintenanceIntegrates OpenAI Codex CLI with Claude Code via MCP, enabling code execution, analysis, fixing, and web search within Claude Code.2,084 npm1ISC
- AlicenseNot gradedqualityDmaintenanceEnables Claude Code Desktop to call OpenAI Codex/GPT-5 and Gemini APIs via stdio MCP, without requiring local CLI tools.MIT
- AlicenseBqualityDmaintenanceMCP bridge for using local Claude CLI as a bounded reviewer and analysis delegate for Codex.5MIT