codex_bridge
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| CODEX_WAIT_SECONDS | No | Default wait_seconds for Codex MCP tool calls. | 90 |
| CODEX_RPC_TIMEOUT_MS | No | RPC timeout in milliseconds for the Codex app-server bridge; initialize calls are capped at 45000 ms. | 60000 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Bridge to OpenAI Codex via codex app-server. Use codex_run to start or continue coding tasks (use worktree: true for parallel or risky edits) and codex_review for independent read-only code reviews. When status is "inProgress", keep polling with codex_wait; when "waitingForInput", answer pending_requests with codex_respond. For worktree: true tasks, inspect diffs with codex_worktree(action="diff") before merging or removing with codex_worktree(action="remove").
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| codex_runA | Give Codex (OpenAI coding agent) a task. Starts a new thread, or continues an existing one when thread_id is given. Blocks up to wait_seconds, then returns status, Codex's latest message, files changed, diff preview, and commands run. status "inProgress" → codex_wait; "waitingForInput" → answer pending_requests with codex_respond. Run several threads in parallel by calling codex_run with wait_seconds: 0 (prefer worktree: true), then codex_wait with all thread_ids. Verify Codex's diff/changes before reporting them as done. |
| codex_waitB | Wait for turns on one or more Codex threads, then return their reports. mode "all" (default) returns when every thread is done or blocked on a request; "any" returns as soon as one is. |
| codex_statusA | Non-blocking snapshot of Codex threads in this session: status, what Codex is doing right now, pending requests. |
| codex_respondA | Answer a request Codex is blocked on (listed in pending_requests). Approvals take decision: accept | acceptForSession | decline | cancel. Questions take answers: { : "answer" }. Ask the user first for risky/destructive actions or architectural choices. |
| codex_steerB | Add instructions to the turn Codex is currently working on, without stopping it. |
| codex_interruptC | Stop the running turn on a Codex thread. |
| codex_reviewA | Run Codex's native code review (read-only) in a git repo. The review text comes back in the "review" field. Pass focus and/or adversarial: true for a steerable review that challenges assumptions and edge cases. |
| codex_worktreeB | List managed Codex worktrees (~/.codex-mcp/worktrees), inspect git status & diff inside a worktree, or remove a finished worktree. |
| codex_compactB | Summarize a long Codex thread's history to free up its context window. Runs in the background. |
| codex_modelsB | Models available to this Codex login, with supported reasoning efforts. |
| codex_threadsA | List recent Codex threads (including ones from the Codex app/CLI), newest first. Continue one with codex_run + thread_id. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 11 tools
Each tool has a distinct role in the Codex lifecycle (run, wait, status, respond, steer, interrupt, review, worktree, compact, models, threads). The only real overlap risk is codex_status vs codex_wait vs codex_threads, but the descriptions sharply delineate blocking vs non-blocking vs listing behavior.
Every tool follows the same codex_<verb|noun> snake_case pattern with no deviations. Names are short, predictable, and immediately readable.
11 tools is well within the sweet spot, and each maps to a necessary operation (start, observe, interact, control, inspect). No redundant or filler tools are present.
The surface covers the full interaction lifecycle: launch, wait, snapshot, respond to approvals/questions, steer, interrupt, review, compact, and worktree cleanup, plus discovery of models and prior threads. Minor gaps: no explicit thread close/delete or fork operation, and worktree management is limited to list/inspect/remove.