Which integrations are available for this server?

Integrates with the OpenAI Codex CLI to provide AI-assisted coding capabilities, including code analysis, refactoring, and generation with advanced session management and model selection.

How do I use Codex MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Codex MCP Server Refactor this function in session 'api-v2' with high reasoning effort" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Codex MCP Server

npm version npm downloads license

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

graph LR A[Claude Code] --> B[Codex MCP Server] B --> C[codex tool] B --> D[listSessions tool] B --> E[ping tool] B --> F[help tool] C --> G[Codex CLI v0.50.0+] C --> H[Session Storage] style A fill:#FF6B35 style B fill:#4A90E2 style C 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.50.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.50.0+ required (see Version Compatibility below)
Claude Code installed

Version Compatibility

This MCP server requires codex CLI v0.50.0 or later due to the following changes:

v0.50.0+: Introduced --skip-git-repo-check flag (now required)
v0.50.0+: Reasoning effort now 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

Install in VS Code

VS Code Insiders

Install in VS Code Insiders

Cursor

Install in 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.1-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.1-codex)
reasoningEffort (optional): Control reasoning depth ('minimal', 'low', 'medium', 'high')

`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.50.0+)

Session Management

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

Model Selection

Default: gpt-5.1-codex
Override per request with model parameter
Reasoning effort: minimal, low, medium, high

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

License

ISC

Codex MCP Server

Codex MCP Server

Prerequisites

Version Compatibility