ayounce80/openai-mcp-server

OpenAI Codex MCP Server

MCP server for OpenAI Codex (GPT-5) API integration with Claude Code CLI. Access GPT-5-Codex-high when you need that "connect the dots" capability alongside Claude.

Overview

This MCP server enables Claude Code to call GPT-5-Codex models when needed:

• Primary: Claude Sonnet 4.5 for everyday coding
• "Lifesaver": GPT-5-Codex-high for complex problem-solving
• Integration: Both models working together in one environment

Features

• GPT-5-Codex-high: Your "connect the dots" model for complex problems
• GPT-5-Codex: Standard Codex for general tasks
• 1Password Integration: Secure API key management via 1Password CLI
• Streaming Support: Real-time response generation
• Cost Tracking: Monitor API usage (≈$0.26/session)

Prerequisites

• OpenAI API Key with GPT-5-Codex access
• API Credits: $1.25/M input tokens, $10/M output tokens
• Python 3.10+
• Claude Code CLI v2.0+
• 1Password CLI (recommended for secure key management)

Setup

1. Install Dependencies

cd /home/adam/projects/openai-mcp-server
/home/adam/.local/bin/uv venv
/home/adam/.local/bin/uv pip install -e ".[dev]"

2. Configure API Key (1Password - Recommended)

# Install 1Password CLI if needed
# https://developer.1password.com/docs/cli/get-started/

# Sign in to 1Password
eval $(op signin)

# Your API key should already be in 1Password
# We'll reference it when adding to Claude Code

3. Add to Claude Code

# Using 1Password CLI reference
claude mcp add --scope user --transport stdio openai-codex \
  --env OPENAI_API_KEY_1P="op://Private/OpenAI/api_key" -- \
  /home/adam/projects/openai-mcp-server/.venv/bin/python \
  /home/adam/projects/openai-mcp-server/src/openai_server/server.py

# Verify
claude mcp list

4. Alternative: Direct API Key (Less Secure)

claude mcp add --scope user --transport stdio openai-codex \
  --env OPENAI_API_KEY="sk-your-key-here" -- \
  /home/adam/projects/openai-mcp-server/.venv/bin/python \
  /home/adam/projects/openai-mcp-server/src/openai_server/server.py

Usage in Claude Code

Once configured, Claude can access Codex when needed:

Example Prompts

When you need "connect the dots" thinking:

This is complex - use codex_high to analyze this architecture
and help me understand how these pieces fit together

Parallel validation:

Review my solution, then use codex_high to validate
your analysis and catch anything we might have missed

Cost-conscious approach:

Try solving this with your knowledge first.
If you get stuck, use codex_high for help.

Available MCP Tools

1. codex_chat

Standard GPT-5-Codex for general queries and coding.

Parameters:

• prompt (required): The question or task
• model (optional): "gpt-5-codex" (default) or "gpt-5-codex-high"
• temperature (optional): 0-1, default 0.7
• max_tokens (optional): Default 4096

Cost: ~$0.13/session (50k input + 20k output)

2. codex_high

GPT-5-Codex-high for complex "connect the dots" problem-solving.

Parameters:

• prompt (required): The complex problem
• temperature (optional): 0-1, default 0.7
• max_tokens (optional): Default 8192

Cost: ~$0.26/session (50k input + 20k output)

3. codex_stream

Streaming responses for real-time output.

Parameters:

• prompt (required)
• model (optional): "gpt-5-codex" or "gpt-5-codex-high"
• temperature (optional): 0-1, default 0.7

4. list_codex_models

List available Codex models and pricing.

No parameters required

Available MCP Resources

openai://models

JSON with available Codex models and specifications.

openai://config

Current server configuration and API status.

Cost Optimization

Your Usage Pattern

Expected: 5 "lifesaver" sessions/week = 20/month
Session cost: ~$0.26 (50k input + 20k output)
Monthly estimate: $5.20

Conservative (10x usage): ~$52/month
Still saves $148/month vs ChatGPT Pro

Pricing Breakdown

• Input: $1.25 per million tokens
• Output: $10 per million tokens
• Typical session: 50k input + 20k output ≈ $0.26

Best Practices

1. Use Claude first - Try with Sonnet before calling Codex
2. Be specific - Focused prompts = fewer tokens
3. Monitor usage - Set budget alerts on OpenAI dashboard
4. Batch questions - One complex prompt vs multiple simple ones

Use Cases

1. Complex Architecture Analysis

"Use codex_high to analyze how these microservices interact
and identify potential bottlenecks"

2. Algorithm Optimization

"I've implemented this solution. Use codex_high to validate
the approach and suggest optimizations"

3. Debugging Complex Issues

"Use codex_high to help trace through this multi-threaded
race condition and explain what's happening"

4. Second Opinion

"Review my database schema. Then use codex_high to validate
and catch any issues I might have missed"

Testing

Run Smoke Tests

.venv/bin/python -m pytest tests/test_smoke.py -v

Run Integration Tests (requires API key & credits)

export OPENAI_API_KEY="sk-..."
.venv/bin/python -m pytest tests/test_smoke.py -v

Troubleshooting

Server Not Connected

# Check status
claude mcp list

# Server auto-restarts with new conversations

1Password CLI Issues

# Test 1Password CLI
op read "op://Private/OpenAI/api_key"

# Re-signin if needed
eval $(op signin)

API Key Not Working

# Test directly
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

Insufficient Credits

Visit https://platform.openai.com/settings/organization/billing and add credits.

Architecture

Claude Code CLI (Sonnet 4.5)
    ↓ (stdio MCP)
OpenAI Codex MCP Server
    ↓ (OpenAI SDK)
OpenAI API
    → gpt-5-codex
    → gpt-5-codex-high

Development

Project Structure

openai-mcp-server/
├── src/
│   └── openai_server/
│       ├── __init__.py
│       └── server.py          # Main MCP server
├── tests/
│   └── test_smoke.py          # Smoke tests
├── pyproject.toml             # Python config
├── README.md                  # This file
├── .env.example               # Config template
└── .gitignore

Models

gpt-5-codex-high

• Best for: Complex problem-solving, "connecting dots"
• Cost: Same as gpt-5-codex
• Use when: Claude gets stuck or you need validation

gpt-5-codex

• Best for: General coding, standard tasks
• Cost: $1.25/M input, $10/M output
• Use when: Need Codex but not the highest complexity

Security

1Password Integration

• API keys never stored in config files
• 1Password CLI handles secure retrieval
• Automatic session management

Direct Key (Not Recommended)

• Keys stored in ~/.claude.json
• File is protected but not encrypted
• Use 1Password when possible

License

MIT

Resources

• OpenAI API Docs: https://platform.openai.com/docs
• MCP Documentation: https://docs.claude.com/en/docs/claude-code/mcp
• 1Password CLI: https://developer.1password.com/docs/cli
• Claude Code: https://code.claude.com