Codex CLI

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.2.4): Enhanced Windows compatibility - Now using cross-spawn for reliable npm global command execution across all platforms (Windows, macOS, Linux). 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+)

One-Line Setup

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

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", "@cexll/codex-mcp-server"]
}

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", "@cexll/codex-mcp-server"]
    }
  }
}

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

// Use the default gpt-5-codex model
'explain the architecture of @src/';

// Use gpt-5 for fast general purpose reasoning
'use codex with model gpt-5 to analyze @config.json';

// Use o3 for deep reasoning tasks
'use codex with model o3 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 codex-1 for software engineering
'use codex with model codex-1 to refactor @legacy-code.js';

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

Example 2: Quick Automation (Convenience Mode)

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

Example 3: Read-Only Analysis

{
  "sandboxMode": "read-only",
  "model": "gpt-5-codex",
  "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 @cexll/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-codex"
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 Ex

---

README truncated. View full README on GitHub.