Codex MCP Tool

Codex MCP Tool is a 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.

Models are fetched dynamically from the OpenAI API — no hardcoded model lists that go stale. Use the list-models tool to see what's available.

TLDR: Claude Code + 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 (codex login)

One-Line Setup

# Install the MCP server
claude mcp add codex-cli -- npx -y codex-mcp

# Install the pre-push review skill (optional, requires git repo URL)
npx skills add <your-username>/codex-mcp-server --skill codex-pre-push-review

Verify Installation

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

Alternative: Import from Claude Desktop

If you already have it configured in Claude Desktop:

1. Add to your Claude Desktop config:

"codex-cli": {
  "command": "npx",
  "args": ["-y", "codex-mcp"]
}

2. Import to Claude Code:

claude mcp add-from-claude-desktop

Configuration

Register the MCP server with your MCP client:

For NPX Usage (Recommended)

Add this configuration to your Claude Desktop config file:

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

For Global Installation

If you installed globally, use this configuration instead:

{
  "mcpServers": {
    "codex-cli": {
      "command": "codex-mcp"
    }
  }
}

Configuration File Locations:

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

After updating the 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

Models are fetched dynamically from the OpenAI API. Use list-models to see what's currently available.

// Let Codex use whatever model is configured
'explain the architecture of @src/';

// Use a specific model
'use codex with model gpt-5.4 to analyze @config.json';

// Use the most capable coding model
'use codex with model gpt-5.3-codex to refactor @legacy-code.js';

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

// Discover available models
'list available codex models';

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",
  "prompt": "refactor @src/utils for better performance"
}

Example 2: Quick Automation (Convenience Mode)

{
  "sandbox": true,
  "prompt": "fix type errors in @src/"
}

Example 3: Read-Only Analysis

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

Smart Defaults

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

{
  "sandboxMode": "workspace-write",
  "approvalPolicy": "on-failure"
}

Check 2: Use convenience flags

{
  "sandbox": true,
  "prompt": "your task"
}

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:

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 in trusted environments.

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
'ask codex using gpt-5.4 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 — models are fetched dynamically from the OpenAI API
  • 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)
  • 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"

• list-models: Discover available OpenAI models dynamically.

  • Reads directly from the Codex CLI's model cache (~/.codex/models_cache.json) — no API key needed
  • Falls back to OpenAI /v1/models API if Codex CLI cache unavailable
  • Cached for 1 hour, use refresh: true to force-refresh

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

  • Use to verify MCP connection is working

• 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.

Bundled Skill: Pre-Push Review

This repo includes a Claude Code skill that automatically reviews your changes with Codex before any push, PR, or merge — with dynamic model selection based on breaking change risk.

Install the Skill

npx skills add <your-username>/codex-mcp-server --skill codex-pre-push-review

Or install manually by copying skills/codex-pre-push-review/SKILL.md to ~/.claude/skills/codex-pre-push-review/SKILL.md.

What It Does

• Before any git push / gh pr create / merge, Claude uses ask-codex to review your changes
• Flagship model (e.g., gpt-5.3-codex) for breaking changes: API changes, schema migrations, auth/security, dependency bumps, 500+ line diffs
• Fast model (e.g., gpt-5.4-mini) for non-breaking changes: docs, tests, style, small fixes
• Red flags catch rationalizations like "this is too simple to review" or "it's just tests"

Requires

• The codex-mcp MCP server installed (see One-Line Setup above)
• OPENAI_API_KEY set in your environment

Platform Support

| Platform | Status | Notes | |----------|--------|-------| | Windows | Fully Supported | Uses cross-spawn for reliable .cmd handling | | 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)

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.