Purpose
codex-mcp-tool is an MCP server used to connect IDEs or AI assistants such as Claude and Cursor to the local Codex CLI. Through this bridge, editors or AI assistants can call the Codex CLI to perform operations such as code analysis and editing. It is not an official OpenAI product and uses the MIT license.
Main capabilities
- File analysis: supports referencing files with syntax such as @src/ and @package.json.
- Multi-turn sessions: provides conversation continuity with workspace isolation.
- Native resume: uses codex resume to preserve context (requires CLI v0.36.0+).
- Local open-source models: can run via localProvider with Ollama or LM Studio.
- Web search: enables research capabilities via search: true.
- Sandbox mode: implements secure automation via explicit sandbox and approval policies.
- Change mode: outputs structured OLD/NEW patches for refactoring.
- Brainstorming: provides frameworks such as SCAMPER, design thinking, and lateral thinking.
- Health diagnostics: monitors CLI version, features, and sessions.
- Cross-platform: supports Windows, macOS, and Linux.
Image generation
image-gen drives Codex's built-in image_gen tool, uses ChatGPT login, and does not require OPENAI_API_KEY. This tool only accepts prompts and reference image paths: the model and pixel dimensions are determined by Codex, and size, quality, format, or mask parameters are not supported. Therefore image-gen places all control into structured prompts (purpose, asset type, style, composition, exact text, reference characters, edit invariants, aspect ratio, presets), and requires the Codex host model to relay rather than improvise. Images are saved by Codex to $CODEX_HOME/generated_images/<thread>/, and are copied when outputPath is specified; if the file already exists, by default the original file is kept and a -v2 copy is written, unless overwrite: true. The result reports the dimensions and alpha channel of each file, so cases where a transparent background was requested but an opaque one was returned can be flagged.
Models and reasoning depth
The model parameter is omitted by default, and Codex CLI uses the default model in ~/.codex/config.toml (for example model = "gpt-6.1-sol"). Pass model only when a single call needs to override the default. Reasoning depth is calibrated per tool: ask-codex uses the Codex CLI default reasoning (medium), and is increased only when a task needs more planning or checking; brainstorm, do-act, and review-changes default to reasoningEffort: "high". Sol, Astra, and Terra models provide max and ultra reasoning; Luna models top out at max, and gpt-5.5 tops out at xhigh. ultra may delegate work to subagents, and most tasks should remain at medium or high. A concrete slug must be passed: the bare moving aliases gpt-6 and gpt-5.6 are rejected by the API; gpt-6.1-sol is rejected in Codex CLI 0.157.x with the same 400 as an unknown slug, and can be upgraded with npm install -g @openai/codex@latest.
Session management and requirements
Since v1.4.0+, multi-turn sessions and workspace isolation are supported: CODEX_SESSION_TTL_MS controls the session TTL (default 24 hours), and CODEX_MAX_SESSIONS controls the maximum number of sessions (default 50). Codex CLI 0.95.0 or newer is required; older versions give a clear upgrade prompt rather than silently dropping unsupported flags. The upgrade command is npm install -g @openai/codex@latest, and the health tool can be used to view the detected version. Prerequisites: Node.js 18+, and Codex CLI installed and authenticated. Configuration locations: on macOS, ~/Library/Application Support/Claude/claude_desktop_config.json; on Windows, %APPDATA%\Claude\claude_desktop_config.json.
Local open-source models and advanced options
Since v1.6.0+, local Ollama or LM Studio can be used insteadInstead of OpenAI, it requires running Ollama locally and selecting a model that supports tool calling (such as qwen3:8b). Regarding CLI compatibility, it has been verified against Codex CLI 0.144.3; the server retains legacy feature guards, but using the current version is recommended. Key points of current behavior: Codex CLI has removed --full-auto and the on-failure approval policy; MCP's sandbox: true / fullAuto: true are still compatibility aliases for --sandbox workspace-write --ask-for-approval never and will not bypass the sandbox; use native --search instead of the deprecated web_search_request; current exec flags include --strict-config, --ephemeral, --ignore-user-config, --ignore-rules.
Troubleshooting and Version Notes
A health tool is available for diagnosis: 'use health verbose:true'. A common issue is that MCP clients launched from the GUI (Dock, Finder, Start menu) inherit a minimal PATH that may not include Homebrew, nvm, or volta directories, causing codex to be available in the terminal but not found within the app. The server automatically searches these locations; if it still cannot be found, you can explicitly pin the path, whose value can be obtained with which codex, and the health tool will show the resolved executable and how it was resolved. Version evolution: v2.5.x → v2.6.0 syncs with Codex CLI 0.159.2 models and adds the image-gen tool, adds gpt-6.1-sol (requires Codex CLI 0.159+), gpt-6-sol, and gpt-6-luna, with the breaking change of removing gpt-5.4-mini (now returns HTTP 400). v2.4.x → v2.5.0 is compatible with Codex CLI 0.153.4, adds gpt-6-astra, removes gpt-5.4 and the mobile alias gpt-5.6 (both return HTTP 400), and removes the untrusted approval policy that 0.153.x no longer parses. v2.3.x → v2.4.0 audits Codex CLI 0.144.3, adds GPT-5.6 Sol/Terra/Luna, max/ultra reasoning, current exec flags, native search only, and provides safe compatibility handling for the removed --full-auto and on-failure approval policies. v2.2.x → v2.3.0 sets gpt-5.5 as the new default, adds gpt-5.4-mini, and removes 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 sets gpt-5.4 as the new default model and updates the fallback chain. v1.5.x → v1.6.0 supports local open-source models (localProvider, oss), defaults to gpt-5.3-codex, and xhigh reasoning. v1.3.x → v1.4.0 adds the sessionId parameter, list-sessions/health tools, and structured error handling, with no breaking changes.
Applicable Scenarios and Limitations
Suitable for bridging the local Codex CLI within IDEs or AI assistants such as Claude and Cursor, for development tasks including code analysis, multi-turn editing, sandbox automation, refactoring patch generation, brainstorming, and image generation. Usage limitations include: Codex CLI (0.95.0+) and Node.js 18+ must be installed and authenticated in advance; GUI-launched environments may have PATH issues; some model slugs and legacy flags are rejected by the API or CLI; local models require Ollama and support for tool calling; information such as fees, pricing, specific platforms, or effectiveness is not yet provided and is subject to the actual configuration.
