Codex Bridge

🚀 Codex Bridge

Codex Bridge is a lightweight MCP server that allows AI coding assistants to interact with OpenAI's Codex AI via the official CLI. It's compatible with various MCP clients, offering simplicity, reliability, and seamless integration.

✨ Features

• Direct Codex CLI Integration: Utilize the official Codex CLI without incurring API costs.
• Simple MCP Tools: Two core functions for basic queries and file analysis.
• Stateless Operation: No need for sessions, caching, or complex state management.
• Production Ready: Robust error handling with configurable timeouts (default: 90 seconds).
• Minimal Dependencies: Only requires mcp>=1.0.0 and the Codex CLI.
• Easy Deployment: Supports both uvx and traditional pip installation methods.
• Universal MCP Compatibility: Works with any MCP-compatible AI coding assistant.

🚀 Quick Start

Prerequisites

1. Install Codex CLI:

   npm install -g @openai/codex-cli
   

2. Authenticate with Codex:

   codex
   

3. Verify installation:

   codex --version
   

Installation

🎯 Recommended: PyPI Installation

# Install from PyPI
pip install codex-bridge

# Add to Claude Code with uvx (recommended)
claude mcp add codex-bridge -s user -- uvx codex-bridge

Alternative: From Source

# Clone the repository
git clone https://github.com/shelakh/codex-bridge.git
cd codex-bridge

# Build and install locally
uvx --from build pyproject-build
pip install dist/*.whl

# Add to Claude Code
claude mcp add codex-bridge -s user -- uvx codex-bridge

Development Installation

# Clone and install in development mode
git clone https://github.com/shelakh/codex-bridge.git
cd codex-bridge
pip install -e .

# Add to Claude Code (development)
claude mcp add codex-bridge-dev -s user -- python -m src

🌐 Multi-Client Support

Codex Bridge is compatible with any MCP-compatible AI coding assistant. The same server can support multiple clients through different configuration methods.

Supported MCP Clients

• Claude Code ✅ (Default)
• Cursor ✅
• VS Code ✅
• Windsurf ✅
• Cline ✅
• Void ✅
• Cherry Studio ✅
• Augment ✅
• Roo Code ✅
• Zencoder ✅
• Any MCP-compatible client ✅

Configuration Examples

# Recommended installation
claude mcp add codex-bridge -s user -- uvx codex-bridge

# Development installation
claude mcp add codex-bridge-dev -s user -- python -m src

{
  "mcpServers": {
    "codex-bridge": {
      "command": "uvx",
      "args": ["codex-bridge"],
      "env": {}
    }
  }
}

{
  "mcpServers": {
    "codex-bridge": {
      "command": "uvx",
      "args": ["codex-bridge"],
      "env": {}
    }
  }
}

{
  "servers": {
    "codex-bridge": {
      "type": "stdio",
      "command": "uvx",
      "args": ["codex-bridge"]
    }
  }
}

{
  "mcpServers": {
    "codex-bridge": {
      "command": "uvx",
      "args": ["codex-bridge"],
      "env": {}
    }
  }
}

{
  "mcpServers": {
    "codex-bridge": {
      "command": "uvx",
      "args": ["codex-bridge"],
      "env": {}
    }
  }
}

{
  "mcpServers": {
    "codex-bridge": {
      "command": "uvx",
      "args": ["codex-bridge"],
      "env": {}
    }
  }
}

"augment.advanced": { 
  "mcpServers": [ 
    { 
      "name": "codex-bridge", 
      "command": "uvx", 
      "args": ["codex-bridge"],
      "env": {}
    }
  ]
}

{
  "mcpServers": {
    "codex-bridge": {
      "command": "uvx",
      "args": ["codex-bridge"],
      "env": {}
    }
  }
}

{
  "command": "uvx",
  "args": ["codex-bridge"],
  "env": {}
}

{
  "command": "codex-bridge",
  "args": [],
  "env": {}
}

{
  "command": "python",
  "args": ["-m", "src"],
  "env": {},
  "cwd": "/path/to/codex-bridge"
}

{
  "command": "npx",
  "args": ["codex-bridge"],
  "env": {}
}

Universal Usage

Once configured with any client, you can use the same two tools:

1. Ask general questions: "What authentication patterns are used in this codebase?"
2. Analyze specific files: "Review these auth files for security issues"

The server implementation remains the same - only the client configuration differs!

⚙️ Configuration

Timeout Configuration

By default, Codex Bridge uses a 90-second timeout for all CLI operations. For longer queries (e.g., large files, complex analysis), you can configure a custom timeout using the CODEX_TIMEOUT environment variable.

Git Repository Check

By default, Codex CLI requires being inside a Git repository or trusted directory. If you need to use Codex Bridge in directories that aren't Git repositories, you can set the CODEX_SKIP_GIT_CHECK environment variable.

⚠️ Important Note

Only enable this flag in trusted environments where you control the directory structure.

Example configurations:

# Add with custom timeout (120 seconds)
claude mcp add codex-bridge -s user --env CODEX_TIMEOUT=120 -- uvx codex-bridge

# Add with git repository check disabled (for non-git directories)
claude mcp add codex-bridge -s user --env CODEX_SKIP_GIT_CHECK=true -- uvx codex-bridge

# Add with both configurations
claude mcp add codex-bridge -s user --env CODEX_TIMEOUT=120 --env CODEX_SKIP_GIT_CHECK=true -- uvx codex-bridge

{
  "mcpServers": {
    "codex-bridge": {
      "command": "uvx",
      "args": ["codex-bridge"],
      "env": {
        "CODEX_TIMEOUT": "120",
        "CODEX_SKIP_GIT_CHECK": "true"
      }
    }
  }
}

Configuration Options:

🛠️ Available Tools

consult_codex

A direct CLI bridge for simple queries, with structured JSON output by default.

Parameters:

• query (string): The question or prompt to send to Codex.
• directory (string): Working directory for the query (default: current directory).
• format (string): Output format - "text", "json", or "code" (default: "json").
• timeout (int, optional): Timeout in seconds (recommended: 60 - 120, default: 90).

Example:

consult_codex(
    query="Find authentication patterns in this codebase",
    directory="/path/to/project",
    format="json",  # Default format
    timeout=90      # Default timeout
)

consult_codex_with_stdin

A CLI bridge that accepts stdin content for pipeline-friendly execution.

Parameters:

• stdin_content (string): Content to pipe as stdin (e.g., file contents, diffs, logs).
• prompt (string): The prompt to process the stdin content.
• directory (string): Working directory for the query.
• format (string): Output format - "text", "json", or "code" (default: "json").
• timeout (int, optional): Timeout in seconds (recommended: 60 - 120, default: 90).

consult_codex_batch

Designed for batch processing multiple queries, ideal for CI/CD automation.

Parameters:

• queries (list): List of query dictionaries with 'query' and optional 'timeout'.
• directory (string): Working directory for all queries.
• format (string): Output format - currently only "json" is supported for batch processing.

Example:

consult_codex_with_stdin(
    stdin_content=open("src/auth.py").read(),
    prompt="Analyze this auth file and suggest improvements",
    directory="/path/to/project",
    format="json",  # Default format
    timeout=120     # Custom timeout for complex analysis
)

💻 Usage Examples

Basic Code Analysis

# Simple research query
consult_codex(
    query="What authentication patterns are used in this project?",
    directory="/Users/dev/my-project"
)

Detailed File Review

# Analyze specific files
with open("/Users/dev/my-project/src/auth.py") as f:
    auth_content = f.read()
    
consult_codex_with_stdin(
    stdin_content=auth_content,
    prompt="Review this file and suggest security improvements",
    directory="/Users/dev/my-project",
    format="json",  # Structured output
    timeout=120     # Allow more time for detailed analysis
)

Batch Processing

# Process multiple queries at once
consult_codex_batch(
    queries=[
        {"query": "Analyze authentication patterns", "timeout": 60},
        {"query": "Review database implementations", "timeout": 90},
        {"query": "Check security vulnerabilities", "timeout": 120}
    ],
    directory="/Users/dev/my-project",
    format="json"  # Always JSON for batch processing
)

🏗️ Architecture

Core Design

• CLI-First: Makes direct subprocess calls to the codex command.
• Stateless: Each tool call is independent, with no session state.
• Configurable Timeout: Has a default execution time of 90 seconds, which is configurable.
• Structured Output: Uses JSON format by default for better integration.
• Simple Error Handling: Provides clear error messages with a fail-fast approach.

Project Structure

codex-bridge/
├── src/
│   ├── __init__.py              # Entry point
│   ├── __main__.py              # Module execution entry point
│   └── mcp_server.py            # Main MCP server implementation
├── .github/                     # GitHub templates and workflows
├── pyproject.toml              # Python package configuration
├── README.md                   # This file
├── CONTRIBUTING.md             # Contribution guidelines
├── CODE_OF_CONDUCT.md          # Community standards
├── SECURITY.md                 # Security policies
├── CHANGELOG.md               # Version history
└── LICENSE                    # MIT license

🔧 Development

Local Testing

# Install in development mode
pip install -e .

# Run directly
python -m src

# Test CLI availability
codex --version

Integration with Claude Code

The server automatically integrates with Claude Code when properly configured through the MCP protocol.

🔍 Troubleshooting

CLI Not Available

# Install Codex CLI
npm install -g @openai/codex-cli

# Authenticate
codex auth login

# Test
codex --version

Connection Issues

• Verify that the Codex CLI is properly authenticated.
• Check your network connectivity.
• Ensure that the Claude Code MCP configuration is correct.
• Confirm that the codex command is in your PATH.

Common Error Messages

• "CLI not available": Indicates that the Codex CLI is not installed or not in the PATH.
• "Authentication required": Run codex auth login to authenticate.
• "Timeout after X seconds": The query took too long. Try increasing the timeout or breaking the query into smaller parts.

🤝 Contributing

We welcome contributions from the community! Please read our Contributing Guidelines for details on how to get started.

Quick Contributing Guide

1. Fork the repository.
2. Create a feature branch.
3. Make your changes.
4. Add tests if applicable.
5. Submit a pull request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔄 Version History

See CHANGELOG.md for detailed version history.

🆘 Support

• Issues: Report bugs or request features via GitHub Issues.
• Discussions: Join the community discussion.
• Documentation: Additional documentation can be created in the docs/ directory.

Focus: A simple, reliable bridge between Claude Code and Codex AI through the official CLI.