Skip to main content
Glama

Codex Bridge

CI Status PyPI Version MIT License Python 3.10+ MCP Compatible Codex CLI

A lightweight MCP (Model Context Protocol) server that enables AI coding assistants to interact with OpenAI's Codex AI through the official CLI. Works with Claude Code, Cursor, VS Code, and other MCP-compatible clients. Designed for simplicity, reliability, and seamless integration.

✨ Features

  • Direct Codex CLI Integration: Zero API costs using official Codex CLI

  • Simple MCP Tools: Two core functions for basic queries and file analysis

  • Stateless Operation: No 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 Codex CLI

  • Easy Deployment: Support for both uvx and traditional pip installation

  • Universal MCP Compatibility: Works with any MCP-compatible AI coding assistant

Related MCP server: Ambiance MCP Server

šŸš€ 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 works with any MCP-compatible AI coding assistant - the same server supports 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

Global Configuration (~/.cursor/mcp.json):

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

Project-Specific (.cursor/mcp.json in your project):

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

Go to: Settings → Cursor Settings → MCP → Add new global MCP server

Configuration (.vscode/mcp.json in your workspace):

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

Alternative: Through Extensions

  1. Open Extensions view (Ctrl+Shift+X)

  2. Search for MCP extensions

  3. Add custom server with command: uvx codex-bridge

Add to your Windsurf MCP configuration:

{
  "mcpServers": {
    "codex-bridge": {
      "command": "uvx",
      "args": ["codex-bridge"],
      "env": {}
    }
  }
}
  1. Open Cline and click MCP Servers in the top navigation

  2. Select Installed tab → Advanced MCP Settings

  3. Add to cline_mcp_settings.json:

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

Go to: Settings → MCP → Add MCP Server

{
  "mcpServers": {
    "codex-bridge": {
      "command": "uvx",
      "args": ["codex-bridge"],
      "env": {}
    }
  }
}
  1. Navigate to Settings → MCP Servers → Add Server

  2. Fill in the server details:

    • Name: codex-bridge

    • Type: STDIO

    • Command: uvx

    • Arguments: ["codex-bridge"]

  3. Save the configuration

Using the UI:

  1. Click hamburger menu → Settings → Tools

  2. Click + Add MCP button

  3. Enter command: uvx codex-bridge

  4. Name: Codex Bridge

Manual Configuration:

"augment.advanced": { 
  "mcpServers": [ 
    { 
      "name": "codex-bridge", 
      "command": "uvx", 
      "args": ["codex-bridge"],
      "env": {}
    }
  ]
}
  1. Go to Settings → MCP Servers → Edit Global Config

  2. Add to mcp_settings.json:

{
  "mcpServers": {
    "codex-bridge": {
      "command": "uvx",
      "args": ["codex-bridge"],
      "env": {}
    }
  }
}
  1. Go to Zencoder menu (...) → Tools → Add Custom MCP

  2. Add configuration:

{
  "command": "uvx",
  "args": ["codex-bridge"],
  "env": {}
}
  1. Hit the Install button

For pip-based installations:

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

For development/local testing:

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

For npm-style installation (if needed):

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

Universal Usage

Once configured with any client, 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 is identical - only the client configuration differs!

āš™ļø Configuration

Timeout Configuration

By default, Codex Bridge uses a 90-second timeout for all CLI operations. For longer queries (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.

āš ļø Security Warning: 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:

CODEX_TIMEOUT:

  • Default: 90 seconds (if not configured)

  • Range: Any positive integer (seconds)

  • Recommended: 60-120 seconds for most queries, 120-300 for large file analysis

  • Invalid values: Fall back to 90 seconds with warning

CODEX_SKIP_GIT_CHECK:

  • Default: false (Git repository check enabled)

  • Valid values: "true", "1", "yes" (case-insensitive) to disable the check

  • Use case: Working in directories that are not Git repositories

  • Security: Only use in trusted directories you control

šŸ› ļø Available Tools

consult_codex

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

CLI bridge with stdin content for pipeline-friendly execution.

Parameters:

  • stdin_content (string): Content to pipe as stdin (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

Batch processing for multiple queries - perfect 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" supported for batch

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: Direct subprocess calls to codex command

  • Stateless: Each tool call is independent with no session state

  • Configurable Timeout: 90-second default execution time (configurable)

  • Structured Output: JSON format by default for better integration

  • Simple Error Handling: Clear error messages with 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 Codex CLI is properly authenticated

  • Check network connectivity

  • Ensure Claude Code MCP configuration is correct

  • Check that the codex command is in your PATH

Common Error Messages

  • "CLI not available": Codex CLI is not installed or not in PATH

  • "Authentication required": Run codex auth login

  • "Timeout after X seconds": Query took too long, try increasing timeout or breaking 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 docs can be created in the docs/ directory


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

Available Tools

3 tools
consult_codexA
Consult Codex in non-interactive mode with structured output.

Processes prompt and returns formatted response.
Supports text, JSON, and code extraction formats.

Args:
    query: The prompt to send to Codex
    directory: Working directory (required)
    format: Output format - "text", "json", or "code" (default: "json")
    timeout: Optional timeout in seconds (overrides env var, recommended: 60-120)
    
Returns:
    Formatted response based on format parameter
ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
directoryYes
formatNojson
timeoutNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully disclose behavior. It states the tool is non-interactive and supports multiple output formats, but lacks details on side effects, authentication needs, error conditions, or what happens if the directory is invalid. The return description 'Formatted response' is vague.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with a clear front-loaded purpose statement. It uses a structured Args/Returns format that is efficient. Minor redundancy exists (first sentence already says 'structured output', later repeats 'returns formatted response'), but overall no waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description adequately covers basic parameters and their purpose, but lacks usage context and potential edge cases. Given a 4-parameter tool with required fields and no annotations, it should explain more about output structure (especially since an output schema exists) and error handling. The timeout hint is good but incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage, so the description adds significant value by explaining each parameter: 'query' as the prompt, 'directory' as working directory (required), 'format' with options 'text', 'json', 'code' (default 'json'), and 'timeout' with hint about env var and recommended range. This clarifies meaning beyond the schema's bare type/default.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Consult Codex in non-interactive mode with structured output.' It specifies the action (consult), resource (Codex), and distinguishes from siblings (batch and stdin modes) by explicitly mentioning 'non-interactive mode'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use for single prompts without stdin, but does not explicitly contrast with sibling tools 'consult_codex_batch' or 'consult_codex_with_stdin'. There is no direct guidance on when to choose this tool over alternatives, leaving the agent to infer from the name and siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

consult_codex_batchA
Consult multiple Codex queries in batch - perfect for CI/CD automation.

Processes multiple prompts and returns consolidated JSON output.
Each query can have individual timeout and format preferences.

Args:
    queries: List of query dictionaries with keys: 'query' (required), 'timeout' (optional)
    directory: Working directory (required)
    format: Output format - currently only "json" supported for batch
    
Returns:
    JSON array with all results
ParametersJSON Schema
NameRequiredDescriptionDefault
queriesYes
directoryYes
formatNojson

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided; description discloses basic behavior (batch, JSON output) but lacks details on safety, error handling, or performance considerations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with clear sections, front-loaded purpose, and no irrelevant content. Only minor verbosity in first two sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, parameters, and output adequately for basic usage; lacks some context on error handling or concurrency but sufficient for a simple batch tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Compensates for 0% schema description coverage by thoroughly explaining all parameters, including required keys for queries and format limitation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it consults multiple codex queries in batch, for CI/CD automation, distinguishing from single-query siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implied use for CI/CD batch processing but does not explicitly compare to consult_codex or consult_codex_with_stdin, leaving when-not-to-use unclear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

consult_codex_with_stdinA
Consult Codex with stdin content piped to prompt - pipeline-friendly execution.

Similar to 'echo "content" | codex exec "prompt"' - combines stdin with prompt.
Perfect for CI/CD workflows where you pipe file contents to the AI.

Args:
    stdin_content: Content to pipe as stdin (e.g., file contents, diff, logs)
    prompt: The prompt to process the stdin content
    directory: Working directory (required)
    format: Output format - "text", "json", or "code" (default: "json")
    timeout: Optional timeout in seconds (overrides env var, recommended: 60-120)
    
Returns:
    Formatted response based on format parameter
ParametersJSON Schema
NameRequiredDescriptionDefault
stdin_contentYes
promptYes
directoryYes
formatNojson
timeoutNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided; description only mentions timeout and pipeline nature, lacking disclosure on permissions, side effects, or error handling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Compact structure with summary, analogy, use case, and parameter list; no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers parameters and use case well, but lacks detail on return value variations beyond format parameter and error conditions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema coverage, description adds clear purpose for each parameter, including examples and recommended timeout range, far exceeding minimum.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Describes specific verb 'Consult Codex' with stdin piping, clearly distinguishes from siblings via pipeline-friendly execution and analogy to 'echo | codex exec'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

States perfect for CI/CD workflows and gives usage analogy, but does not explicitly mention when not to use or alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 3 tool updates
    • First observedconsult_codex
    • First observedconsult_codex_batch
    • First observedconsult_codex_with_stdin

TDQS

A4.2/5.0
Disambiguation5/5

Each tool has a distinct purpose: single query, batch processing, and stdin-based interaction. No overlap in functionality, and the parameters clearly differentiate use cases.

Naming Consistency5/5

All tools follow the 'consult_codex' prefix with a clear suffix indicating variant (_batch, _with_stdin). Consistent snake_case with no deviations.

Tool Count5/5

Three tools cover the essential modes of operation (single, batch, stdin) for a Codex bridge server. The count is well-scoped and appropriate for the domain.

Completeness5/5

The tool surface covers all non-interactive consultation modes: single queries, batch processing for CI/CD, and stdin piping. No obvious gaps given the stated non-interactive scope.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables comprehensive codebase analysis using Google's Gemini AI through CLI integration. Provides architectural reviews and targeted code analysis with code2prompt integration for efficient context extraction.
    18
    2
    Apache 2.0
  • A
    license
    A
    quality
    D
    maintenance
    Provides intelligent code context and analysis through semantic compression, AST parsing, and multi-language support. Offers 60-80% token reduction while enabling AI assistants to understand codebases through local analysis, OpenAI-enhanced insights, and GitHub repository integration.
    6
    22
    3
    MIT
  • A
    license
    C
    quality
    F
    maintenance
    Connects AI assistants like Claude to the Codex CLI for code analysis, editing, and execution. Supports file references with @ syntax, sandboxed code execution with approval workflows, and structured code changes for automated refactoring and documentation.
    8
    198
    179
    MIT
  • F
    license
    B
    quality
    D
    maintenance
    Connects AI assistants to a local Codex engine for performing deep, project-level code reviews and automated refactoring. It enables context-aware bug fixes and multi-file analysis through a standardized bridge between modern AI clients and local development environments.
    4
    2
    -

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/eLyiN/codex-bridge'

If you have feedback or need assistance with the MCP directory API, please join our Discord server