| name | codex-mcp |
| description | How to use OpenAI Codex via MCP tools for code generation, plan review, and collaborative implementation loops. Use when calling Codex for implementation, review, or any cross-model collaboration. |
Codex MCP Usage Guide
Tools
| Tool | Purpose |
|---|
mcp__codex__codex | Start a new Codex session. Returns a threadId + response. |
mcp__codex__codex-reply | Continue an existing session using threadId. |
Session Management
Codex sessions are stateful via threadId. Always:
- Save the
threadId from the first mcp__codex__codex call
- Use
mcp__codex__codex-reply with that threadId for all follow-ups
- Never start a new session when continuing the same task — context carries forward
Key Parameters
sandbox
| Mode | When to Use |
|---|
read-only | Plan review, code audit, Q&A — Codex reads but cannot write files |
workspace-write | Implementation — Codex writes files in the project directory |
approval-policy
| Policy | When to Use |
|---|
never | Background agents (no UI → hangs forever on approval prompt). Also review-only tasks. |
on-failure | Foreground implementation — auto-approve commands, intervene on errors |
on-request | Avoid in background — same hang risk as interactive approval |
developer-instructions
Inject a persona or constraints into Codex without polluting the main prompt.
Always include: "Be concise. Do not include your reasoning process in the response. Only output the result."
Resume Loop Pattern (CRITICAL)
Codex frequently returns control after partial progress (reading files, making a few edits).
The caller must resume via codex-reply until Codex reports completion.
Pattern for background agents (bg-codex-implementer)
1. Call mcp__codex__codex with full task prompt → get threadId + partial response
2. While response does not indicate completion:
a. Call mcp__codex__codex-reply(threadId, "continue")
b. Check if Codex says "done", "complete", "all changes made", etc.
3. Write result to .codex_tasks/<task_id>/result.md
Pattern for foreground (main agent)
1. Call mcp__codex__codex → get threadId
2. If Codex returned partial work, call mcp__codex__codex-reply(threadId, "continue implementing")
3. Repeat until done (cap at 5 iterations)
Delegation pattern (background Codex via subagent)
Use a general-purpose Sonnet agent (not a custom Haiku agent) to dispatch to Codex:
Agent(model: "sonnet", isolation: "worktree", run_in_background: true,
prompt: "You are a Codex dispatcher. Call mcp__codex__codex early
with approval-policy='never', sandbox='workspace-write'.
Resume with mcp__codex__codex-reply until done. Codex does
the heavy implementation — you may read files or check output
lightly when needed, but don't implement code yourself.
<full task prompt>")
Why Sonnet? General-purpose subagents inherit MCP tools from the parent session.
Custom agent types (bg-codex-implementer, codex-only, policy-opt-codex-haiku) with
mcpServers: in YAML frontmatter do NOT get MCP tools registered by the runtime.
Confirmed: 0/5 Haiku custom agents succeeded, Sonnet general-purpose agents work reliably.
Prompting Best Practices
- Termination signals: Ask Codex to reply "APPROVED" or "CHANGES NEEDED" — gives clear loop control
- Feedback verbatim: When sending review feedback via codex-reply, quote specific issues exactly. Do not summarize.
- Concise responses: Always instruct Codex to be concise via developer-instructions to save tokens
- Max iterations: Always enforce a hard cap (default: 5) on review loops
stderr Suppression
The MCP server config uses 2>/dev/null at the process level.
Individual tool calls do NOT need stderr suppression — MCP returns structured JSON-RPC responses only.
See reference.md for detailed examples and patterns.
