codex-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Choose/create a project directory with codex_projects, then pass its project_id or an existing absolute workdir to codex_start. No workspace config is required. Select supported options using codex_models. Save task ids and event cursors. Poll codex_events (wait_seconds up to 25) until a turn completes, respond to ask_parent requests, and relay human approvals through codex_review_request or the local review command. Never interpret silence as approval. Reuse request_id only for identical control operations. Use codex_get for summaries and command evidence. On reconnect, replay from the saved cursor; after a backend restart, resume and inspect history before sending more work. Native approve_for_me is selectable with approval_mode; it uses Codex's reviewer, not approval_relay. Use codex_delegate for native delegation and codex_subagents to discover children; parent event polling includes their progress and requests. Check family_status and child statuses before treating delegated work as done. Respect can_accept_direct_input on children. Use settings, fork, queue, review, compact, archive and history controls for the corresponding native workflows. Queued instructions can be consumed immediately: inspect before editing/retrying.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| codex_plansA | 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. |
| codex_statusB | Check installed Codex, sign-in type, pending request summaries and broker health. |
| codex_projectsB | List selected projects with offset/limit; select/create takes path. The main agent chooses an absolute project directory. |
| codex_worktreesB | 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. |
| codex_modelsB | Discover model ids, supported reasoning efforts and defaults. Catalog visibility is not an entitlement guarantee. |
| codex_startB | Start a persistent Codex conversation and return promptly with a task id. Poll codex_events and handle pending_requests until the turn finishes. |
| codex_listB | Page persistent tasks, newest first. Large projections identify truncated_fields. |
| codex_getC | 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. |
| codex_eventsB | 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. |
| codex_sendB | Send a follow-up turn or steer active work. Steering needs the current expected_turn_id; follow-ups can select a supported model/effort. |
| codex_resumeB | Reconcile native history and execution intent after reconnect. No prompt or command replay. Inspect codex_history before a follow-up. |
| codex_interruptA | Ask Codex to interrupt the specified active turn. Poll for interrupted/completed; interrupt acknowledgement alone is not completion. |
| codex_historyB | 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. |
| codex_requestsA | 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. |
| codex_respondA | 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. |
| codex_review_requestC | Human review, or read details with offset=0. Follow next_offset and verify detail_sha256. Acceptance requires complete content. |
| codex_capabilitiesC | Discover native collaboration/permission options and direct-input capability for a task. |
| codex_settingsA | 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. |
| codex_subagentsC | Page verified descendants; parent events include child requests. refresh=false uses offset; refresh=true uses cursor. Respect can_accept_direct_input. |
| codex_delegateB | Ask a parent to manage native subagents; discover them with codex_subagents. Active parents require expected_turn_id. |
| codex_forkA | Fork an idle owned conversation, optionally through a selected turn. Keeps project boundaries; does not start work or automatically continue a goal. |
| codex_renameC | Rename an owned native conversation. |
| codex_archiveA | Archive or restore an idle conversation and its native descendants. Transcripts are retained. |
| codex_deleteA | 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. |
| codex_compactA | Request native history compaction for an idle conversation; may consume model usage. Poll completion events. |
| codex_revertA | Remove a selected turn and all later native conversation history. DOES NOT revert files. Requires explicit acknowledgement; local event audit remains. |
| codex_queueC | 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. |
| codex_reviewB | Start native code review of uncommitted changes, a base branch, a commit or custom instructions on an idle task. Poll for findings/results. |
| codex_terminalsB | list takes cursor/limit; terminate takes process_id; clean stops all background terminals. Mutations need an operation key. No arbitrary shell or stdin. |
| codex_goalA | 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. |
| codex_skillsB | List native skills available for this project. Select enabled skills by name in start/send; no global skill configuration changes. |
| codex_diffA | 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. |
| codex_usageA | Read native account rate limits/remaining allowance. Does not buy credits or change billing. |
| codex_sessionsC | 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. |
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 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.