Codex MCP Tool

Codex MCP Tool is an open‑source Model Context Protocol (MCP) server that connects your IDE or AI assistant (Claude, Cursor, etc.) to the Codex CLI. It enables non‑interactive automation with codex exec, safe sandboxed edits with approvals, and large‑scale code analysis via @ file references. Built for reliability and speed, it streams progress updates, supports structured change mode (OLD/NEW patch output), and integrates cleanly with standard MCP clients for code review, refactoring, documentation, and CI automation.

Latest Release (v1.3.8): Fixed empty ask-codex responses, improved Codex CLI transcript parsing, and repaired release packaging so npm/marketplace updates publish correctly. See changelog

• Ask Codex questions from your MCP client, or brainstorm ideas programmatically.

TLDR: + Codex CLI

Goal: Use Codex directly from your MCP-enabled editor to analyze and edit code efficiently.

Prerequisites

Before using this tool, ensure you have:

1. Node.js (v18.0.0 or higher)
2. Codex CLI installed and authenticated

✅ Cross-Platform Support: Fully tested and working on Windows, macOS, and Linux (v1.2.4+)

Install via Claude Code Marketplace (Recommended)

In Claude Code, run:

/plugin marketplace add etheaven/codex-mcp-server
/plugin install codex-mcp-server@codex-mcp-server

Alternative: CLI Setup

claude mcp add codex-cli -- npx -y @etheaven/codex-mcp-server

Verify Installation

Type /mcp inside Claude Code to verify the Codex MCP is active.

Configuration

Claude Desktop

Add to your Claude Desktop config file:

{
  "mcpServers": {
    "codex-cli": {
      "command": "npx",
      "args": ["-y", "@etheaven/codex-mcp-server"]
    }
  }
}

Config file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/claude/claude_desktop_config.json

Global Installation

npm install -g @etheaven/codex-mcp-server

Then use "command": "codex-mcp" instead of the npx approach.

After updating configuration, restart your terminal session.

Example Workflow

• Natural language: "use codex to explain index.html", "understand this repo with @src", "look for vulnerabilities and suggest fixes"
• Claude Code: Type /codex-cli to access the MCP server tools.

Usage Examples

Model Selection

// Use the default model (gpt-5.4)
'explain the architecture of @src/';

// Use gpt-5.3-codex for complex coding tasks
'use codex with model gpt-5.3-codex to refactor @legacy-code.js';

// Use gpt-5.4 with high reasoning for deep analysis
'use codex with model gpt-5.4 and reasoning high to analyze complex algorithm in @algorithm.py';

// Use o4-mini for quick tasks
'use codex with model o4-mini to add comments to @utils.js';

// Use o3 for deep reasoning
'use codex with model o3 to design microservices architecture for @requirements.md';

// Use gpt-5-mini for cost-effective tasks
'use codex with model gpt-5-mini to summarize @README.md';

With File References (using @ syntax)

• ask codex to analyze @src/main.ts and explain what it does
• use codex to summarize @. the current directory
• analyze @package.json and list dependencies

General Questions (without files)

• ask codex to explain div centering
• ask codex about best practices for React development related to @src/components/Button.tsx

Brainstorming & Ideation

• brainstorm ways to optimize our CI/CD pipeline using SCAMPER method
• use codex to brainstorm 10 innovative features for our app with feasibility analysis
• ask codex to generate product ideas for the healthcare domain with design-thinking approach

Codex Approvals & Sandbox

Codex CLI supports fine-grained control over permissions and approvals through sandbox modes and approval policies.

Understanding Parameters

The sandbox Parameter (Convenience Flag):

• sandbox: true → Enables fullAuto mode (equivalent to fullAuto: true)
• sandbox: false (default) → Does NOT disable sandboxing, just doesn't enable auto mode
• Important: The sandbox parameter is a convenience flag, not a security control

Granular Control Parameters:

• sandboxMode: Controls file system access level
• approvalPolicy: Controls when user approval is required
• fullAuto: Shorthand for sandboxMode: "workspace-write" + approvalPolicy: "on-failure"
• yolo: ⚠️ Bypasses all safety checks (dangerous, not recommended)

Sandbox Modes

| Mode | Description | Use Case | | --------------------- | ------------------------------------ | ------------------------------------------------- | | read-only | Analysis only, no file modifications | Code review, exploration, documentation reading | | workspace-write | Can modify files in workspace | Most development tasks, refactoring, bug fixes | | danger-full-access | Full system access including network | Advanced automation, CI/CD pipelines |

Approval Policies

| Policy | Description | When to Use | | ------------- | -------------------------------- | ----------------------------------- | | never | No approvals required | Fully trusted automation | | on-request | Ask before every action | Maximum control, manual review | | on-failure | Only ask when operations fail | Balanced automation (recommended) | | untrusted | Maximum paranoia mode | Untrusted code or high-risk changes |

Configuration Examples

Example 1: Balanced Automation (Recommended)

{
  "approvalPolicy": "on-failure",
  "sandboxMode": "workspace-write",  // Auto-set if omitted in v1.2+
  "model": "gpt-5.4",
  "prompt": "refactor @src/utils for better performance"
}

Example 2: Quick Automation (Convenience Mode)

{
  "sandbox": true,  // Equivalent to fullAuto: true
  "model": "gpt-5.4",
  "prompt": "fix type errors in @src/"
}

Example 3: Read-Only Analysis

{
  "sandboxMode": "read-only",
  "model": "gpt-5.4",
  "prompt": "analyze @src/ and explain the architecture"
}

Smart Defaults (v1.2+)

Starting from version 1.2.0, the server automatically applies intelligent defaults to prevent permission errors:

• ✅ If approvalPolicy is set but sandboxMode is not → auto-sets sandboxMode: "workspace-write"
• ✅ If search: true or oss: true → auto-sets sandboxMode: "workspace-write" (for network access)
• ✅ All commands include --skip-git-repo-check to prevent errors in non-git environments

Troubleshooting Permission Errors

If you encounter ❌ Permission Error: Operation blocked by sandbox policy:

Check 1: Verify sandboxMode

# Ensure you're not using read-only mode for write operations
{
  "sandboxMode": "workspace-write",  // Not "read-only"
  "approvalPolicy": "on-failure"
}

Check 2: Use convenience flags

# Let the server handle defaults
{
  "sandbox": true,  // Simple automation
  "prompt": "your task"
}

Check 3: Update to latest version

# v1.2+ includes smart defaults to prevent permission errors
npm install -g @etheaven/codex-mcp-server@latest

Common Issues

Issue 1: MCP Tool Timeout Error

If you encounter timeout errors when using Codex MCP tools:

# Set the MCP tool timeout environment variable (in milliseconds)
export MCP_TOOL_TIMEOUT=36000000  # 10 hours

# For Windows (PowerShell):
$env:MCP_TOOL_TIMEOUT=36000000

# For Windows (CMD):
set MCP_TOOL_TIMEOUT=36000000

Add this to your shell profile (~/.bashrc, ~/.zshrc, or PowerShell profile) to make it permanent.

Issue 2: Codex Cannot Write Files

If Codex responds with permission errors like "Operation blocked by sandbox policy" or "rejected by user approval settings", configure your Codex CLI settings:

Create or edit ~/.codex/config.toml:

# Dynamically generated Codex configuration
model = "gpt-5.4"
model_reasoning_effort = "high"
model_reasoning_summary = "detailed"
approval_policy = "never"
sandbox_mode = "danger-full-access"
disable_response_storage = true
network_access = true

⚠️ Security Warning: The danger-full-access mode grants Codex full file system access. Only use this configuration in trusted environments and for tasks you fully understand.

Configuration File Locations:

• macOS/Linux: ~/.codex/config.toml
• Windows: %USERPROFILE%\.codex\config.toml

After updating the configuration, restart your MCP client (Claude Desktop, Claude Code, etc.).

Basic Examples

• use codex to create and run a Python script that processes data
• ask codex to safely test @script.py and explain what it does

Default Behavior:

• All codex exec commands automatically include --skip-git-repo-check to avoid unnecessary git repository checks, as not all execution environments are git repositories.
• This prevents permission errors when running Codex in non-git directories or when git checks would interfere with automation.

Advanced Examples

// Using ask-codex with specific model and reasoning effort
'ask codex using gpt-5.3-codex with reasoning high to refactor @utils/database.js for better performance';

// Brainstorming with constraints
"brainstorm solutions for reducing API latency with constraints: 'must use existing infrastructure, budget under $5k'";

// Change mode for structured edits
'use codex in change mode to update all console.log to use winston logger in @src/';

Tools (for the AI)

These tools are designed to be used by the AI assistant.

Core Tools

• ask-codex: Sends a prompt to Codex via codex exec.

  • Supports @ file references for including file content
  • Optional model parameter — recommended models:
    • gpt-5.4 (default, latest flagship)
    • gpt-5.3-codex (best for complex coding)
    • gpt-5.3-codex-spark (instant coding, Pro only)
    • o3 (deep reasoning)
    • o4-mini (fast & efficient)
    • gpt-5-mini (cost-effective)
    • gpt-4.1 (1M context, no reasoning)
    • See full model list
  • Optional reasoningEffort parameter: none, minimal, low, medium, high, xhigh
  • sandbox=true enables --full-auto mode
  • changeMode=true returns structured OLD/NEW edits
  • Supports approval policies and sandbox modes
  • Automatically includes --skip-git-repo-check to prevent permission errors in non-git environments

• brainstorm: Generate novel ideas with structured methodologies.

  • Multiple frameworks: divergent, convergent, SCAMPER, design-thinking, lateral
  • Domain-specific context (software, business, creative, research, product, marketing)
  • Supports same models and reasoningEffort as ask-codex
  • Configurable idea count and analysis depth
  • Includes feasibility, impact, and innovation scoring
  • Example: brainstorm prompt:"ways to improve code review process" domain:"software" methodology:"scamper"

• ping: A simple test tool that echoes back a message.

  • Use to verify MCP connection is working
  • Example: /codex-cli:ping (MCP) "Hello from Codex MCP!"

• help: Shows the Codex CLI help text and available commands.

Advanced Tools

• fetch-chunk: Retrieves cached chunks from changeMode responses.

  • Used for paginating large structured edit responses
  • Requires cacheKey and chunkIndex parameters

• timeout-test: Test tool for timeout prevention.

  • Runs for a specified duration in milliseconds
  • Useful for testing long-running operations

Slash Commands (for the User)

You can use these commands directly in Claude Code's interface (compatibility with other clients has not been tested).

• /analyze: Analyzes files or directories using Codex, or asks general questions.
  • prompt (required): The analysis prompt. Use @ syntax to include files (e.g., /analyze prompt:@src/ summarize this directory) or ask general questions (e.g., /analyze prompt:Please use a web search to find the latest news stories).
• /sandbox: Safely tests code or scripts with Codex approval modes.
  • prompt (required): Code testing request (e.g., /sandbox prompt:Create and run a Python script that processes CSV data or /sandbox prompt:@script.py Test this script safely).
• /help: Displays the Codex CLI help information.
• /ping: Tests the connection to the server.
  • message (optional): A message to echo back.

Recent Updates

v1.3.8 (2026-03-30)

📦 Release Fix:

• Added search-insights to devDependencies so npm ci passes in the GitHub release workflow
• This is the first publishable release that includes the empty ask-codex response fix

v1.3.7 (2026-03-30)

📦 Release Fix:

• Synced package-lock.json with package.json so the GitHub release workflow can complete npm ci and publish successfully
• Carries forward the empty ask-codex response fix from the failed v1.3.6 release attempt

v1.3.6 (2026-03-30)

🐛 Bug Fixes:

• Fixed empty ask-codex responses when Codex CLI emitted the usable transcript on stderr
• Reworked output parsing to handle role-based transcript sections like user, codex, and assistant
• Prevented the formatter from returning a bare **Response:** header when no response content was parsed

📦 Release Metadata:

• Synced npm, lockfile, and Claude marketplace/plugin metadata to version 1.3.6

v1.3.0 (2026-03-15)

Model Support Overhaul:

• Updated model list to March 2026: added gpt-5.4, gpt-5.4-pro, gpt-5.3-codex, gpt-5.3-codex-spark, gpt-5.2-codex, gpt-5.2, gpt-5.1-codex-max, gpt-5.1-codex, gpt-5.1, gpt-5-pro, gpt-5-mini, gpt-5-nano, o3-pro, gpt-4.1-mini, gpt-4.1-nano
• Removed deprecated models: codex-1 and codex-mini-latest (never existed in OpenAI API)
• New reasoningEffort parameter for ask-codex, brainstorm, and batch-codex tools — supports none, minimal, low, medium, high, xhigh
• Improved tool schema descriptions with exact valid model IDs to prevent AI clients from inventing model names
• Updated default model recommendation from gpt-5-codex to gpt-5.4
• Comprehensive model documentation rewrite with per-model reasoning effort support tables

v1.2.4 (2025-10-27)

🔧 Major Improvement:

• Windows Compatibility Enhancement: Replaced Node.js native spawn() with industry-standard cross-spawn package
  • Root cause: Previous shell: true fix still failed on some Windows configurations
  • Solution: Use cross-spawn (50M+ weekly downloads, used by Webpack/Jest) for automatic Windows .cmd handling
  • Benefits:
    • Zero configuration required for Windows users
    • Automatic handling of .cmd, .ps1, and .exe extensions
    • Compatible with both CMD and PowerShell environments
    • <5ms performance overhead
  • Dependencies: Added cross-spawn@^7.0.6 and @types/cross-spawn

🐛 Bug Fixes:

• Enhanced ENOENT error diagnostics with Windows-specific 4-step troubleshooting guide
• Added optional chaining for stdout/stderr to handle null values in TypeScript strict mode

📝 Documentation:

• Added comprehensive Windows troubleshooting section in docs
• Documented spawn codex ENOENT error resolution steps

v1.2.3 (2025-10-27)

🐛 Bug Fixes:

• Windows Compatibility: Fixed Codex CLI detection failing on Windows despite proper installation
  • Root cause: spawn() with shell: false couldn't resolve .cmd extensions on Windows
  • Solution: Enabled shell mode for cross-platform command execution
  • Impact: Zero performance impact (~10ms overhead), maintains security with array-form arguments
  • Platforms verified: Windows, macOS, Linux via GitHub Actions CI

📝 Documentation:

• Updated all package references from @trishchuk/codex-mcp-tool to @etheaven/codex-mcp-server (now hosted at etheaven/codex-mcp-server)
• Enhanced cross-platform setup instructions

🔍 Testing:

• CI/CD now validates on Ubuntu, macOS, and Windows across Node.js 18.x, 20.x, and 22.x

v1.2.2 & Earlier

• Smart sandbox mode defaults to prevent permission errors
• Enhanced debug information for troubleshooting
• Automatic --skip-git-repo-check flag for non-git environments
• Web search integration with feature flags
• Structured change mode with pagination support

Platform Support

| Platform | Status | Notes | |----------|--------|-------| | Windows | ✅ Fully Supported | Enhanced in v1.2.4 with cross-spawn | | macOS | ✅ Fully Supported | Tested on Darwin 23.5.0+ | | Linux | ✅ Fully Supported | Tested on Ubuntu Latest |

Minimum Requirements:

• Node.js v18.0.0 or higher
• Codex CLI installed and authenticated (npm install -g @openai/codex)

Acknowledgments

This project was inspired by the excellent work from jamubc/gemini-mcp-tool. Special thanks to @jamubc for the original MCP server architecture and implementation patterns.

Contributing

Contributions are welcome! Please submit pull requests or report issues through GitHub.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Disclaimer: This is an unofficial, third-party tool and is not affiliated with, endorsed, or sponsored by OpenAI.