Codex MCP Server Integration

Skill by ara.so — MCP Skills collection.

Overview

Codex MCP Server bridges Claude Code, Cursor, and other MCP-compatible editors with OpenAI's Codex CLI. It provides AI-powered code analysis, generation, review, and web search capabilities through the Model Context Protocol (MCP).

Architecture:

Claude Code/Cursor → Codex MCP Server → Codex CLI → OpenAI API

Installation

Step 1: Install Codex CLI

# Via npm (recommended)
npm install -g @openai/codex

# Via Homebrew
brew install codex

# Verify installation
codex --version  # Should be 0.75.0 or higher

Step 2: Authenticate Codex CLI

# Set your OpenAI API key
codex login --api-key "$OPENAI_API_KEY"

# Verify authentication
codex ping

Step 3: Install MCP Server

For Claude Code:

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

Manual configuration (add to MCP settings file):

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

With static callback URI:

{
  "mcpServers": {
    "codex-cli": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "codex-mcp-server"],
      "env": {
        "CODEX_MCP_CALLBACK_URI": "http://localhost:8080/mcp-callback"
      }
    }
  }
}

Available Tools

1. codex — AI Coding Assistant

The main tool for code analysis, generation, and assistance.

Basic usage:

// Ask a simple question about code
codex({
  prompt: "Explain what this function does and suggest improvements",
  context: ["src/auth/login.ts"]
})

Parameters:

• prompt (required): Your question or instruction
• context (optional): Array of file paths to include
• sessionId (optional): Resume a previous conversation
• model (optional): Override model (e.g., "o3", "gpt-4")
• reasoningEffort (optional): "low", "medium", "high" for reasoning models
• fullAuto (optional): Enable autonomous mode
• sandbox (optional): Sandbox permissions ("read-only", "workspace-write")
• callbackUri (optional): MCP callback URI for this request
• structuredContent (optional): Return threadId and structured metadata

Response includes:

• response: The AI's text response
• threadId: Conversation thread ID (if available from Codex 0.87+)
• metadata: Additional context about the response

2. review — Code Review

AI-powered code review for uncommitted changes, branches, or commits.

Review uncommitted changes:

review({
  uncommitted: true
})

Review a branch:

review({
  base: "main",
  head: "feature/new-api"
})

Review specific commits:

review({
  commit: "abc123..def456"
})

Parameters:

• uncommitted (optional): Review uncommitted changes
• base (optional): Base branch for comparison
• head (optional): Head branch/commit to review
• commit (optional): Specific commit or range
• model (optional): Override model
• reasoningEffort (optional): Reasoning level

3. websearch — Web Search

Search the web using Codex CLI's integrated search.

websearch({
  query: "React Server Components best practices 2025",
  numResults: 10,
  searchDepth: "full"
})

Parameters:

• query (required): Search query
• numResults (optional): Number of results (default: 10)
• searchDepth (optional): "quick" or "full" (default: "quick")

4. listSessions — View Active Sessions

List all active conversation sessions for this server instance.

listSessions()

Returns array of session objects with id and messageCount.

5. ping — Test Connection

Verify the server is responding.

ping()

6. help — Get CLI Help

Get help information from Codex CLI.

help({
  command: "review"  // Optional: specific command
})

Common Patterns

Multi-Turn Conversations

Use sessionId to maintain context across multiple interactions:

// Start a refactoring session
codex({
  prompt: "Analyze this authentication module for security issues",
  context: ["src/auth/index.ts"],
  sessionId: "auth-refactor"
})

// Continue in the same session
codex({
  prompt: "Implement the security fixes you suggested",
  sessionId: "auth-refactor"
})

// Follow up with more questions
codex({
  prompt: "Add unit tests for the new security checks",
  sessionId: "auth-refactor"
})

// Check active sessions
listSessions()
// Returns: [{ id: "auth-refactor", messageCount: 3 }]

Code Analysis Workflows

Security audit:

codex({
  prompt: "Perform a security audit focusing on: 1) Input validation, 2) Authentication bypasses, 3) SQL injection risks, 4) XSS vulnerabilities",
  context: ["src/api/**/*.ts"],
  model: "o3",
  reasoningEffort: "high"
})

Performance optimization:

codex({
  prompt: "Identify performance bottlenecks and suggest optimizations with Big O analysis",
  context: ["src/services/data-processor.ts"],
  sessionId: "perf-optimization"
})

Refactoring guidance:

codex({
  prompt: "Suggest refactoring to improve maintainability: extract reusable patterns, reduce complexity, improve naming",
  context: ["src/legacy/user-manager.js"]
})

Pre-Commit Code Review

// Review all uncommitted changes
review({
  uncommitted: true,
  model: "gpt-4"
})

// Review specific branch before PR
review({
  base: "main",
  head: "feature/user-permissions",
  reasoningEffort: "high"
})

Research and Documentation

// Find latest best practices
websearch({
  query: "TypeScript 5.8 new features decorators",
  numResults: 15,
  searchDepth: "full"
})

// Learn about a library
websearch({
  query: "Prisma vs TypeORM 2025 comparison pros cons",
  numResults: 10
})

// Then ask codex to help implement
codex({
  prompt: "Based on current best practices, help me migrate this ORM code to Prisma",
  context: ["src/models/user.ts"]
})

Autonomous Mode with Sandbox

For tasks that require file modifications:

codex({
  prompt: "Implement a REST API endpoint for user registration with validation, error handling, and tests",
  fullAuto: true,
  sandbox: "workspace-write",
  context: ["src/api/routes/"]
})

Sandbox modes:

• "read-only": Can read but not modify files
• "workspace-write": Can create/modify files in workspace

Using Thread IDs (Codex 0.87+)

When using Codex CLI 0.87+, capture thread IDs for conversation tracking:

const result = codex({
  prompt: "Design a caching strategy for this API",
  context: ["src/api/handlers.ts"],
  structuredContent: true
})

// result.threadId available for tracking
// result.metadata contains additional context

Configuration

Environment Variables

CODEX_MCP_CALLBACK_URI: Set a static MCP callback URI for all requests.

export CODEX_MCP_CALLBACK_URI="http://localhost:8080/mcp-callback"

This can be overridden per-request using the callbackUri parameter in the codex tool.

Model Selection

Override the default model for specific tasks:

// Use reasoning model for complex logic
codex({
  prompt: "Design a distributed locking mechanism",
  model: "o3",
  reasoningEffort: "high"
})

// Use faster model for simple tasks
codex({
  prompt: "Add JSDoc comments to this function",
  model: "gpt-4-turbo"
})

Codex CLI Configuration

Check your Codex CLI configuration:

# View current config
codex config list

# Set default model
codex config set model gpt-4

# View authentication status
codex whoami

Troubleshooting

"Codex CLI not found"

Solution:

# Verify installation
which codex

# Reinstall if needed
npm install -g @openai/codex@latest

# Ensure it's in PATH
echo $PATH

"Authentication failed"

Solution:

# Re-authenticate
codex login --api-key "$OPENAI_API_KEY"

# Verify key is valid
codex ping

"Session not found"

Sessions are scoped to the MCP server instance. They reset when the server restarts.

Solution:

• List active sessions: listSessions()
• Start a new session with the same ID to resume conceptually

"Version compatibility error"

Solution:

# Check Codex CLI version
codex --version

# Update to latest
npm update -g @openai/codex

# Minimum required: 0.75.0
# Recommended: 0.87.0+ for thread ID support

"Model not available"

Some models require specific API access.

Solution:

// Fallback to widely available model
codex({
  prompt: "your prompt",
  model: "gpt-4"  // or omit to use default
})

Server not responding

Solution:

# Test server connection
ping()

# Restart MCP server in editor
# For Claude Code: Reload window or restart
# For Cursor: Reload window

# Check MCP logs in editor's output panel

Best Practices

1. Use sessions for related work: Group related questions in a session to maintain context.

2. Provide context files: Always include relevant files in the context array for better responses.

3. Choose appropriate models: Use reasoning models (o3 + reasoningEffort: "high") for complex logic, faster models for simple tasks.

4. Review before merging: Use review tool on branches before creating PRs.

5. Leverage web search: Combine websearch with codex to incorporate latest best practices.

6. Scope sandbox permissions: Use "read-only" by default; only use "workspace-write" when file modifications are needed.

7. Track conversations: Use structuredContent: true with Codex 0.87+ to capture thread IDs for audit trails.

Example Integration Script

// workflow-helper.ts - Automated code review workflow

async function preCommitWorkflow() {
  // 1. Review uncommitted changes
  const reviewResult = await review({
    uncommitted: true,
    reasoningEffort: "high"
  });
  
  console.log("Review:", reviewResult.review);
  
  // 2. If issues found, get fix suggestions
  if (reviewResult.issues?.length > 0) {
    const fixes = await codex({
      prompt: `These issues were found in code review:\n${reviewResult.issues.join('\n')}\n\nProvide specific fixes with code examples.`,
      sessionId: "pre-commit-fixes"
    });
    
    console.log("Suggested fixes:", fixes.response);
  }
  
  // 3. Search for related best practices
  const research = await websearch({
    query: "TypeScript error handling best practices 2025",
    numResults: 5
  });
  
  console.log("Best practices:", research.results);
}

// Run before committing
preCommitWorkflow();

Related Resources

• Codex CLI Documentation: Run codex help or visit OpenAI documentation
• MCP Protocol: https://modelcontextprotocol.io
• API Reference: See project's docs/api-reference.md
• Session Management: See project's docs/session-management.md