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

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

# Via Homebrew
brew install codex

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

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

# Verify authentication
codex ping

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

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

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

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

review({
  uncommitted: true
})

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

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

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

listSessions()

ping()

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

// 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 }]

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"
})

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

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

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

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

// 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"]
})

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/"]
})

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

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

// 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"
})

# View current config
codex config list

# Set default model
codex config set model gpt-4

# View authentication status
codex whoami

# Verify installation
which codex

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

# Ensure it's in PATH
echo $PATH

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

# Verify key is valid
codex ping

# 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

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

# 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

// 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();