Claude - Codex integration

claude_codex.md

OpenAI Codex MCP Integration for Claude Code

Quick setup guide to use OpenAI Codex as a code reviewer within Claude Code via MCP.

---

Prerequisites

• Claude Code installed
• Node.js and npm installed
• OpenAI Codex installed

---

Installation

Replace YOUR_API_KEY_HERE with your actual OpenAI API key:

macOS/Linux:

claude mcp add --scope user --transport stdio codex \
  --env OPENAI_API_KEY=YOUR_API_KEY_HERE \
  -- npx -y @openai/codex mcp serve

Windows (PowerShell):

claude mcp add --scope user --transport stdio codex --env OPENAI_API_KEY=YOUR_API_KEY_HERE -- npx -y @openai/codex mcp serve

---

Verification

1. Check MCP connection:

claude mcp list

You should see: codex: npx -y @openai/codex mcp serve - ✓ Connected

2. Test with Claude:

Start a Claude Code session and ask:

"Use the Codex MCP to answer: what is 2+2?"

If you get a response, it's working!

---

Usage

Just ask Claude naturally to use Codex:

"Write a user authentication function, then ask Codex to review it for security issues"
"Ask Codex to review src/parser.py for bugs and performance issues"
"Get Codex's opinion on this implementation approach before we start"

Claude will:

1. Read/write the code
2. Send it to Codex via MCP for review
3. Get feedback (bugs, security, suggestions)
4. Evaluate which suggestions are valid
5. Implement improvements
6. Report findings

---

Critical Configuration

The MCP will hang forever if misconfigured!

✅ Correct:

mcp__codex__codex(
    prompt="Review this code...",
    approval_policy="never",    # Required!
    sandbox="read-only"
)

❌ Wrong (hangs indefinitely):

mcp__codex__codex(
    prompt="Review this code...",
    approval_policy="on-request"  # Never use this!
)

Why? approval_policy="on-request" waits for interactive user approval that never comes, causing an infinite hang.

Note: You don't need to write this code yourself - Claude handles the MCP calls. This is just documentation of what Claude needs to do correctly.

---

Troubleshooting

"codex: ✗ Failed to connect"

Check:

1. Your OpenAI API key is valid: echo $OPENAI_API_KEY (macOS/Linux) or $env:OPENAI_API_KEY (Windows)
2. The @openai/codex package is accessible: npx @openai/codex --version
3. Run claude mcp list to see detailed error messages

MCP calls hang forever

Solution: Remind Claude to use approval_policy="never" in the MCP call.

Reviews are too generic

Provide more context in your request:

• Explain what the code does
• Mention specific concerns (security, performance, edge cases)
• Include relevant constraints or requirements

Need to update API key

Remove and re-add the MCP server:

claude mcp remove codex
# Then run the installation command again with new API key

---

Example Session

You: "Write a function to divide two numbers, then ask Codex to review it."

Claude writes:

def divide(a, b):
    return a / b

Claude asks Codex for review...

Codex responds:

"Missing zero division check on line 2. Will raise ZeroDivisionError if b=0."

Claude fixes:

def divide(a, b):
    if b == 0:
        raise ValueError("Cannot divide by zero")
    return a / b

Claude reports:

"Codex identified a critical issue - no zero division handling. I've implemented the fix above."

---

Uninstallation

claude mcp remove codex

---

License

MIT - Use freely!

Created by: Joey Marshall Resources:

• Claude Code Documentation
• OpenAI Codex