Codex MCP Server

MCP server for OpenAI Codex CLI v0.75.0+ with session management, model selection, code review, and native resume support.

graph LR
    A[Claude Code] --> B[Codex MCP Server]

    B --> C[codex tool]
    B --> R[review tool]
    B --> D[listSessions tool]
    B --> E[ping tool]
    B --> F[help tool]

    C --> G[Codex CLI v0.75.0+]
    C --> H[Session Storage]
    R --> G

    style A fill:#FF6B35
    style B fill:#4A90E2
    style C fill:#00D4AA
    style R fill:#00D4AA
    style D fill:#00D4AA
    style E fill:#00D4AA
    style F fill:#00D4AA
    style G fill:#FFA500
    style H fill:#9B59B6

Prerequisites

• OpenAI Codex CLI v0.75.0+ must be pre-installed and configured
  • Install: npm i -g @openai/codex or brew install codex
  • Setup: Run codex login --api-key "your-openai-api-key"
  • ⚠️ Breaking Change: OPENAI_API_KEY environment variable is no longer supported
  • ⚠️ Version Requirement: v0.75.0+ required for full feature support (see Version Compatibility below)
• Claude Code installed

Version Compatibility

This MCP server requires codex CLI v0.75.0 or later for full feature support:

• v0.75.0+: Added codex exec review for code reviews
• v0.75.0+: Added sandbox mode (--sandbox read-only|workspace-write|danger-full-access)
• v0.75.0+: Added full-auto mode (--full-auto)
• v0.50.0+: Introduced --skip-git-repo-check flag (now required)
• v0.50.0+: Reasoning effort configured via -c model_reasoning_effort=X flag

If you have an older version of codex CLI, you will need to upgrade:

npm update -g @openai/codex

For detailed version compatibility information, see docs/codex-cli-integration.md.

Installation

One-Click Installation

VS Code

VS Code Insiders

Cursor

Manual Installation

Claude Code

claude mcp add codex-cli -- npx -y codex-mcp-server

Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%/Claude/claude_desktop_config.json

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

Usage in Claude Code

Once installed, Claude Code can use these tools:

codex - Code Assistant

Run Codex queries with optional session support for multi-turn conversations.

Basic Usage:

Use the codex tool to explain this function:
[paste your code here]

Advanced Usage:

# Model selection (defaults to gpt-5.2-codex)
Use codex with model "gpt-4" to analyze this complex algorithm

# Reasoning effort control
Use codex with reasoningEffort "high" for thorough code review

# Session with model override
Use codex with sessionId "my-session" and model "gpt-4" to refactor this code

# Continue conversation (uses native codex resume)
Use codex with sessionId "my-session" to make it more efficient

# Reset session context
Use codex with sessionId "my-session" and resetSession true to start fresh analysis

Parameters:

• prompt (required): Your coding question or request
• sessionId (optional): Session ID for conversational context
• resetSession (optional): Reset session history before processing
• model (optional): Model to use (defaults to gpt-5.2-codex)
• reasoningEffort (optional): Control reasoning depth ('minimal', 'low', 'medium', 'high')
• sandbox (optional): Sandbox policy ('read-only', 'workspace-write', 'danger-full-access')
• fullAuto (optional): Enable full-auto mode for sandboxed automatic execution
• workingDirectory (optional): Working directory for the agent

review - Code Review

Run AI-powered code reviews against your repository using Codex CLI.

Basic Usage:

Use the review tool to review my uncommitted changes

Advanced Usage:

# Review changes against main branch
Use review with base "main" to review my PR changes

# Review a specific commit
Use review with commit "abc123" to analyze this commit

# Review with custom instructions
Use review with prompt "Focus on security vulnerabilities" and uncommitted true

Parameters:

• prompt (optional): Custom review instructions or focus areas
• uncommitted (optional): Review staged, unstaged, and untracked changes
• base (optional): Review changes against a specific base branch
• commit (optional): Review changes introduced by a specific commit SHA
• title (optional): Title to display in the review summary
• model (optional): Model to use for the review
• workingDirectory (optional): Working directory containing the repository

listSessions - Session Management

List all active conversation sessions with metadata including creation time, last access, and turn count.

Usage:

Use listSessions to see all active coding sessions

ping - Connection Test

Test if the MCP server is working properly.

help - Codex CLI Help

Get information about Codex CLI capabilities and commands.

Example Workflows

Code Analysis:

Please use the codex tool to review this TypeScript function and suggest improvements

Conversational Code Development:

# Start a session for complex refactoring
Use codex with sessionId "refactor-auth" to analyze this authentication system

# Continue building on the analysis
Use codex with sessionId "refactor-auth" to implement the security improvements you suggested

# Check session history
Use listSessions to see all active development sessions

Bug Fixing:

Use codex to help debug this error: [error message]

Code Generation:

Ask codex to create a React component that handles file uploads

Advanced Features (Codex CLI v0.75.0+)

MCP 2025-11-25 Specification Compliance

This server implements the latest MCP specification features:

Tool Annotations - Each tool includes metadata hints for clients: | Tool | readOnlyHint | destructiveHint | idempotentHint | openWorldHint | |------|---------------|-------------------|------------------|-----------------| | codex | false | true | false | true | | review | true | false | true | true | | ping | true | false | true | false | | help | true | false | true | false | | listSessions | true | false | true | false |

Progress Notifications - For long-running operations (codex, review), the server sends notifications/progress messages when the client provides a progressToken. This enables real-time streaming feedback during execution.

Note: Progress notification display depends on client support. As of December 2025, some MCP clients receive but don't display these notifications in the UI.

Code Review (New in v0.75.0)

• Review uncommitted changes, branches, or specific commits
• Custom review instructions and focus areas
• Integration with git workflow

Session Management

• Uses codex exec resume for conversation continuity
• Falls back to manual context building when resume unavailable
• Sessions persist for 24 hours
• 58 tests covering functionality and edge cases

Model Selection

• Default: gpt-5.2-codex
• Override per request with model parameter
• Supported: gpt-5.2-codex, gpt-5.1-codex, gpt-5.1-codex-max, gpt-5-codex, gpt-4o, gpt-4, o3, o4-mini
• Reasoning effort: minimal, low, medium, high

Sandbox Mode (New in v0.75.0)

• read-only: No writes allowed
• workspace-write: Writes only in workspace directory
• danger-full-access: Full system access (use with caution)

Full-Auto Mode (New in v0.75.0)

• Sandboxed automatic execution without approval prompts
• Equivalent to -a on-request --sandbox workspace-write

Authentication

• OPENAI_API_KEY env var no longer supported
• Run codex login --api-key "your-key" instead
• Credentials stored in CODEX_HOME/auth.json

Development

# Install dependencies
npm install

# Development mode
npm run dev

# Build
npm run build

# Start built server
npm start

Documentation

• Session Management
• Codex CLI Integration
• API Reference

License

ISC