codex-mcp-tool
A bridge from Claude/Cursor to the Codex CLI, exposing Codex's analysis, editing, review and ideation power as MCP tools.
Analyze code — ask anything about your repo, referencing files with
@pathsyntax, with optional images and web search.Control execution — pick models, working directories, sandbox modes, approval policies, reasoning depth, timeouts, output token caps, config overrides, feature flags, profiles and structured JSON output.
Multi-turn sessions — keep conversation continuity via native Codex resume, reset contexts, and list/delete/clear stored sessions.
Batch tasks — fan out multiple atomic Codex tasks sequentially or in parallel with concurrency limits and stop-on-error.
Code review — run native
codex reviewon the working tree, a base branch, or a specific commit (read-only).Act-check-fix — execute a task, verify it with a shell command and expected exit code, and auto-retry fixes.
Brainstorm — generate ideas using SCAMPER, design-thinking, lateral or divergent/convergent frameworks with feasibility analysis.
Refactor safely — return structured OLD/NEW patch output in change mode, paged through a chunk cache.
Run local models — point Codex at Ollama or LM Studio instead of OpenAI.
Diagnose — check CLI path/version/auth/session health, list available skills, fetch help and version info, echo/ping, and test timeouts.
Bypass safety (careful) —
yolo/danger-full-accessoptions exist for unrestricted runs.
Allows using local OSS models via Ollama as a provider for Codex tasks, enabling offline/local code analysis and generation.
Provides integration with OpenAI's Codex CLI, enabling AI agents to execute coding tasks, perform file analysis, run multi-turn sessions, sandboxed edits, and structured change-mode operations.
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-mcp-tool analyze @package.json and list dependencies"
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 MCP Server
MCP server connecting Claude/Cursor to Codex CLI. Enables code analysis via @ file references, multi-turn conversations, sandboxed edits, and structured change mode.
The project page on trishchuk.com gives an overview of the server: setup, the tool reference, model recommendations and Codex CLI compatibility notes. It also links to a case study on using this server as an outside advisor to Claude Code.
Features
File Analysis — Reference files with
@src/,@package.jsonsyntaxMulti-Turn Sessions — Conversation continuity, isolated per working directory
Native Resume — Uses
codex exec resumeand keeps the session's modelCode Review — Native
codex reviewin a read-only sandboxAct-Check-Fix —
do-actruns a task, verifies it with a shell command, and retries in the same conversationImage Generation — Codex's built-in
image_genwith a structured prompt specLocal OSS Models — Run with Ollama or LM Studio via
localProviderWeb Search — Research capabilities with
search: trueSandbox Mode — Safe automation with explicit sandbox and approval policies
Change Mode — Structured OLD/NEW patch output for refactoring
Brainstorming — SCAMPER, design-thinking, lateral thinking frameworks
Cancellation — Cancelling a tool call stops the Codex process
Health Diagnostics — CLI path, version, authentication, and sessions
Cross-Platform — Windows, macOS, Linux fully supported
Related MCP server: codex-mcp-server
Quick Start
claude mcp add codex-cli -- npx -y @trishchuk/codex-mcp-toolPrerequisites: Node.js 18+, Codex CLI installed and authenticated.
Configuration
{
"mcpServers": {
"codex-cli": {
"command": "npx",
"args": ["-y", "@trishchuk/codex-mcp-tool"]
}
}
}Config locations: macOS: ~/Library/Application Support/Claude/claude_desktop_config.json | Windows: %APPDATA%\Claude\claude_desktop_config.json
Usage Examples
// File analysis
'explain the architecture of @src/';
'analyze @package.json and list dependencies';
// With specific model
'use codex with model gpt-6-astra to analyze @algorithm.py';
// Multi-turn conversations (v1.4.0+)
'ask codex sessionId:"my-project" prompt:"explain @src/"';
'ask codex sessionId:"my-project" prompt:"now add error handling"';
// Code review of the working tree
'review-changes uncommitted:true';
// Do the task, verify with tests, retry on failure
'do-act task:"fix the failing date parser" verify:{command:"npm test"}';
// Brainstorming
'brainstorm ways to optimize CI/CD using SCAMPER method';
// Sandbox mode
'use codex sandbox:true to create and run a Python script';
// Web search
'ask codex search:true prompt:"latest TypeScript 5.7 features"';
// Local OSS model (Ollama)
'ask codex localProvider:"ollama" model:"qwen3:8b" prompt:"explain @src/"';Tools
Tool | Description |
| Execute Codex CLI with files, models, sessions, and safety controls |
| Run multiple atomic Codex tasks sequentially or concurrently |
| Run the native Codex review ( |
| Execute, verify with a shell command, and retry fixes |
| Generate or edit images with Codex's built-in |
| Generate ideas with structured creative frameworks |
| View, delete, or clear MCP conversation mappings |
| List project ( |
| Diagnose CLI path, version, authentication, and sessions |
| Retrieve a chunk from cached change-mode output |
| Test the MCP connection |
| Return current |
| Report Codex CLI, Node.js, platform, and package versions |
| Exercise keepalive and timeout behavior (only with |
Image generation
image-gen drives Codex's built-in image_gen tool, so it uses your ChatGPT
login and needs no OPENAI_API_KEY. That tool only accepts a prompt and
reference image paths: Codex picks the image model and pixel size, and there
are no size, quality, format or mask arguments. image-gen therefore puts all
steering into a structured prompt (use case, asset type, style, composition,
exact text, reference roles, edit invariants, aspect ratio, presets) and tells
the Codex host model to relay it instead of improvising.
// New image, 16:9, exact Cyrillic headline, copied into the project
'image-gen prompt:"YouTube cover about AI coding agents" aspect:"wide" text:"АГЕНТИ БЕЗ ХАОСУ" presets:["thumbnail","exact-text"] outputPath:"assets/cover.png"';
// Edit: change only the headline, keep everything else
'image-gen editImage:"assets/cover.png" prompt:"Replace the headline text" text:"ЧАСТИНА 2" preserve:["people and background"] outputPath:"assets/cover.png"';Images are saved by Codex under $CODEX_HOME/generated_images/<thread>/ and
copied to outputPath when given; an existing file is kept and the copy is
written as a -v2 sibling unless overwrite: true. The result reports each
file's dimensions and alpha channel, so a transparentBackground request that
came back opaque is flagged.
Models
By default the model parameter is omitted and Codex CLI applies the
default model from your ~/.codex/config.toml (for example model = "gpt-6.1-sol").
Pass model only when you need to override the configured default for a
single call. Reasoning depth is calibrated per tool:
ask-codex— uses the Codex CLI default reasoning (medium). Increase it only when the task needs more planning or checking.brainstorm,do-act,review-changes— defaultreasoningEffort: "high"(creative ideation, act-check-fix loops, and code review benefit from deeper reasoning).
Model | Recommendation |
| Latest workhorse for coding and everyday work (CLI 0.159+) |
| Frontier intelligence for the most demanding work |
| Fast, efficient: visual reasoning, computer use, writing |
| Previous-generation workhorse |
| Fast and affordable; easier, repeatable tasks |
| Older-generation workhorse |
| Older balanced model for straightforward work |
| Older fast, efficient model |
gpt-5.5 was retired for ChatGPT sign-in on 2026-10-14; with API-key auth it
still runs and is passed through as an unlisted slug.
Sol, Astra and Terra models expose max and ultra reasoning; Luna models top
out at max. ultra may delegate work to subagents;
most tasks should remain on medium or high. Pass a concrete slug — the bare
moving aliases gpt-6 and gpt-5.6 are rejected by the API. gpt-6.1-sol is
rejected by Codex CLI 0.157.x with the same 400 an unknown slug gets; upgrade
with npm install -g @openai/codex@latest.
Key Features
Session Management
Multi-turn conversations resume the native Codex thread (codex exec resume):
{ "prompt": "analyze code", "sessionId": "my-session", "model": "gpt-6-luna" }
{ "prompt": "continue from here", "sessionId": "my-session" } // still gpt-6-luna
{ "prompt": "start fresh", "sessionId": "my-session", "resetSession": true }A session remembers its model: a follow-up without
modelstays on it instead of switching to your config default.Sessions are bound to their working directory. Reusing the same
sessionIdin another directory starts a separate conversation there, and both stay resumable; switching git branches in the same directory keeps it.list-sessions action:deletetakes an optionalworkingDirto remove just one of them.Sessions live in memory (
CODEX_SESSION_TTL_MS, default 24h;CODEX_MAX_SESSIONS, default 50) and are lost when the server restarts.
Working directory
Codex runs in, by priority: the workingDir argument → CODEX_MCP_CWD →
the project of the first @path in the prompt → PWD/INIT_CWD → the server's
current directory. A workingDir that does not exist is an error — the call is
refused rather than run (and possibly edit files) somewhere else.
Errors and cancellation
Failed calls return isError: true with a categorized message (model, auth,
rate limit, timeout, sandbox, network, session, cancelled). Only Codex's own
ERROR: lines are classified, so an unknown model is reported as a model
error. Cancelling a tool call from the client stops the running codex process;
a run stopped by a timeout or the output limit is never returned as a result.
Codex CLI version
Requires Codex CLI 0.95.0 or newer. On older versions the server fails
with an explicit upgrade message rather than silently dropping unsupported
flags. Upgrade with npm install -g @openai/codex@latest; run the health tool
to see the detected version.
Troubleshooting: "codex not found"
MCP clients launched from a GUI (Dock, Finder, Start menu) inherit a minimal
PATH that excludes Homebrew, nvm, and volta directories, so codex may work
from a terminal but not from the app. The server searches those locations
automatically; if it still cannot find the CLI, pin it explicitly:
{ "env": { "CODEX_CLI_PATH": "/opt/homebrew/bin/codex" } }Find the value with which codex. Run the health tool to see which
executable was resolved and how.
Local OSS Models (v1.6.0+)
Run with local Ollama or LM Studio instead of OpenAI:
// Ollama
{ "prompt": "analyze @src/", "localProvider": "ollama", "model": "qwen3:8b" }
// LM Studio
{ "prompt": "analyze @src/", "localProvider": "lmstudio", "model": "my-model" }
// Auto-select provider
{ "prompt": "analyze @src/", "oss": true }Requirements: Ollama running locally with a model that supports tool calling (e.g. qwen3:8b).
Advanced Options
Parameter | Description |
| Model selection |
| Enable conversation continuity |
| Compatibility automation: workspace-write + never |
| Enable web search |
| Structured OLD/NEW edits |
| Additional writable directories |
| Cap response verbosity (100-10,000) |
| low, medium, high, xhigh, max, ultra |
| Use local OSS model provider |
| Local provider: |
| Fail on unknown Codex configuration keys |
| Do not persist Codex session files |
| Ignore |
| Ignore execpolicy |
|
|
| Layer |
| Per-call limit in ms (positive integer) |
Environment variables
Variable | Purpose |
| Absolute path to |
| Working directory for every call without |
| Session lifetime in ms (default 86400000 = 24h) |
| Maximum stored sessions (default 50) |
|
|
CLI Compatibility
Validated against Codex CLI 0.169.0 (minimum 0.95.0). Notable current behavior:
--full-autoand theon-failure/untrustedapproval policies have been removed by Codex CLI.MCP
sandbox: true/fullAuto: trueremain compatibility aliases for--sandbox workspace-write --ask-for-approval never; they do not bypass the sandbox.approvalPolicy: "on-request"is accepted, but non-interactivecodex execruns still reportapproval: never— nobody can answer a prompt.profileuses profile V2 files ($CODEX_HOME/<name>.config.toml). Codex refuses-p <name>whileconfig.tomlstill has a legacy[profiles.<name>]table, andstrictConfigfails on such tables too.Prompts are passed after
--, so a prompt that starts with-(a markdown list) works; prompts over 100 KB go over stdin.Native
--searchis used without the deprecatedweb_search_requestfeature.
Troubleshooting
codex --version # Check CLI version
codex login status # Check authentication (exit 0 = logged in)
codex login # AuthenticateUse health tool for diagnostics: 'use health verbose:true'
Development
npm run build # compile to dist/
npm run lint # type-check
npm test # build + node --test suite (no extra dependencies)Migration
v2.6.x → v2.7.0: bug-fix release from the 2026-11-14 audit (see CHANGELOG).
Added gpt-6.1-terra. Breaking: an explicit workingDir that does not
exist is now an error instead of a silent fallback; @path references in the
prompt now take priority over PWD; gpt-5.5 is no longer listed (retired for
ChatGPT sign-in — with API-key auth it still passes through); timeout-test is
registered only with CODEX_MCP_TEST_TOOLS=1. Failed tool calls now return
isError: true.
v2.5.x → v2.6.0: Codex CLI 0.159.2 model sync and a new image-gen tool.
Added gpt-6.1-sol (needs Codex CLI 0.159+), gpt-6-sol and gpt-6-luna.
Breaking: dropped gpt-5.4-mini, which now returns HTTP 400.
v2.4.x → v2.5.0: Codex CLI 0.153.4 compatibility pass; added
gpt-6-astra. Breaking: dropped gpt-5.4 and the moving alias gpt-5.6
(both now rejected with HTTP 400), and removed the untrusted approval policy,
which Codex CLI 0.153.x no longer parses.
v2.3.x → v2.4.0: Codex CLI 0.144.3 compatibility audit; added GPT-5.6
Sol/Terra/Luna, max/ultra reasoning, current exec flags, native-only search,
and safe compatibility handling for the removed --full-auto flag and
on-failure approval policy.
v2.2.x → v2.3.0: gpt-5.5 as new default, added gpt-5.4-mini, dropped retired models (gpt-5.3-codex-spark, gpt-5.2-codex, gpt-5.1-codex-max, gpt-5.1-codex-mini).
v2.0.x → v2.1.0: gpt-5.4 as new default model, updated fallback chain.
v1.5.x → v1.6.0: Local OSS model support (localProvider, oss), gpt-5.3-codex default model, xhigh reasoning effort.
v1.3.x → v1.4.0: New sessionId parameter, list-sessions/health tools, structured error handling. No breaking changes.
License
MIT License. Not affiliated with OpenAI.
Documentation | Issues | Inspired by jamubc/gemini-mcp-tool
Available Tools
13 toolsask-codexCDestructive
Execute Codex CLI with file analysis (@syntax), skills ($syntax), model selection, and safety controls. Supports changeMode.
Inputs: prompt (required), cd, oss, yolo, +35 more.
batch-codexADestructive
Delegate multiple atomic tasks to Codex for batch processing. Ideal for repetitive operations, mass refactoring, and automated code transformations
Inputs: tasks (required), oss, model, search, +8 more. Returns: total, failed, results, skipped, +1 more
brainstormC
Generate creative ideas using structured frameworks with domain context and feasibility analysis.
Inputs: prompt (required), cd, oss, yolo, +16 more.
do-actBDestructive
Execute task via Codex, verify with shell command, auto-fix on failure. Act-Check-Fix loop.
Inputs: task (required), oss, model, verify, +7 more. Returns: steps, status, attempts, durationMs
fetch-chunkARead-onlyIdempotent
Retrieves cached chunks from a changeMode response. Use this to get subsequent chunks after receiving a partial changeMode response.
Inputs: cacheKey (required), chunkIndex (required).
healthCRead-onlyIdempotent
Check Codex CLI and session health status
Inputs: verbose, sessionId. Returns: error, issues, status, codexCli, +2 more
helpCRead-onlyIdempotent
receive help information
Inputs: no named parameters.
image-genA
Generate or edit images with Codex's built-in image_gen tool (ChatGPT login, no API key). Builds a structured prompt from use case, style, composition, exact text, reference roles and edit invariants, then returns the saved file paths. The image model and pixel size are chosen by Codex; aspect ratio and transparency are requested through the prompt.
Inputs: prompt (required), text, avoid, model, +21 more. Returns: spec, error, images, status, +4 more
list-sessionsBDestructive
List all active conversation sessions with metadata, or manage sessions
Inputs: action, sessionId, workingDir. Returns: error, stats, action, deleted, +3 more
list-skillsARead-onlyIdempotent
Discover available Codex skills: project .agents/skills and .codex/skills, plus user $CODEX_HOME/skills and ~/.agents/skills
Inputs: workingDir. Returns: error, skills, baseDir
pingCRead-onlyIdempotent
Echo
Inputs: prompt.
review-changesBRead-onlyIdempotent
Run a code review against the current repository using Codex CLI native review subcommand
Inputs: base, model, title, commit, +5 more.
versionARead-onlyIdempotent
Display version and system information
Inputs: no named parameters. Returns: nodeJs, codexCli, platform, mcpServer
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
ask-codex, do-act, batch-codex, and brainstorm all ultimately wrap the same Codex CLI execution, differentiated mainly by prompt framing and verification loops rather than distinct resources. review-changes is close to ask-codex as well, since a review is just a specialized Codex invocation. The descriptions do help separate single-task, batch, act-check-fix, and ideation modes, but an agent could easily pick the wrong wrapper.
All names use kebab-case, which is good, but the conventions are mixed: verb_noun (ask-codex, list-skills, review-changes, fetch-chunk), bare nouns/utilities (health, version, help, ping), and modifier_noun (image-gen, batch-codex). do-act is vague compared to its siblings, and ask-codex vs batch-codex vs do-act do not read as a coherent family.
13 tools is a well-scoped size for a CLI-wrapper server. A few slots are boilerplate (ping, help, version) rather than real capabilities, but overall each tool corresponds to a plausible use case.
Core execution paths are covered: single ask, batch, verified act, review, image generation, skills discovery, session listing, health, and chunk retrieval. However, sessions can only be listed/managed vaguely with no get/delete/detail tool, and there is no way to cancel or abort a long-running Codex run, which are common lifecycle gaps for this domain.
Maintenance
Related MCP Connectors
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Real-time chat for AI agents. Claude Code, Cursor, Cline and Codex join channels over MCP.
Augments MCP Server - A comprehensive framework documentation provider for Claude Code
Real-time chat hub for AI agents — Claude Code, Cursor, Cline, Codex over MCP or REST.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server that integrates Codex CLI into Claude Code workflows for code writing, execution, and review with session management. It features real-time progress monitoring via a local HTTP dashboard and supports detailed configuration for various coding tools.613 npm167MIT
- AlicenseBqualityCmaintenanceAn open-source MCP server that connects your IDE or AI assistant to the Codex CLI, enabling non-interactive automation with codex exec, safe sandboxed edits with approvals, and large-scale code analysis via @ file references.1014 npmMIT
- FlicenseNot gradedqualityDmaintenanceAn MCP server wrapping the Cursor CLI agent, enabling Claude Code and other MCP clients to delegate tasks to Cursor's AI agent for file writing, bash commands, and codebase queries.-
- AlicenseNot gradedqualityCmaintenanceAn MCP server that bridges CLI coding agents like Claude Code, Codex, opencode, and Antigravity into any MCP client, enabling synchronous and asynchronous task execution, follow-up input, and a structured code review tool.24 npm3MIT