# Codex MCP Server Integration

> Use OpenAI Codex CLI through MCP to get AI-powered code analysis, generation, review, and web search directly in your editor

- Skill: `aradotso/codex-mcp-server-integration` (Agent Skill)
- Install (CLI): `npx skillmds@latest add aradotso/codex-mcp-server-integration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aradotso/codex-mcp-server-integration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: aradotso (https://skillmd.com/u/aradotso)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aradotso/codex-mcp-server-integration

---


# Codex MCP Server Integration

> Skill by [ara.so](https://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

```bash
# 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

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

# Verify authentication
codex ping
```

### Step 3: Install MCP Server

**For Claude Code:**
```bash
claude mcp add codex-cli -- npx -y codex-mcp-server
```

**Manual configuration** (add to MCP settings file):

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

**With static callback URI:**
```json
{
  "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:**
```typescript
// 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:**
```typescript
review({
  uncommitted: true
})
```

**Review a branch:**
```typescript
review({
  base: "main",
  head: "feature/new-api"
})
```

**Review specific commits:**
```typescript
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.

```typescript
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.

```typescript
listSessions()
```

Returns array of session objects with `id` and `messageCount`.

### 5. ping — Test Connection

Verify the server is responding.

```typescript
ping()
```

### 6. help — Get CLI Help

Get help information from Codex CLI.

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

## Common Patterns

### Multi-Turn Conversations

Use `sessionId` to maintain context across multiple interactions:

```typescript
// 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:**
```typescript
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:**
```typescript
codex({
  prompt: "Identify performance bottlenecks and suggest optimizations with Big O analysis",
  context: ["src/services/data-processor.ts"],
  sessionId: "perf-optimization"
})
```

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

### Pre-Commit Code Review

```typescript
// 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

```typescript
// 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:

```typescript
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:

```typescript
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.

```bash
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:

```typescript
// 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:

```bash
# 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:**
```bash
# Verify installation
which codex

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

# Ensure it's in PATH
echo $PATH
```

### "Authentication failed"

**Solution:**
```bash
# 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:**
```bash
# 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:**
```typescript
// Fallback to widely available model
codex({
  prompt: "your prompt",
  model: "gpt-4"  // or omit to use default
})
```

### Server not responding

**Solution:**
```bash
# 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

```typescript
// 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`