Codex MCP Bridge

codex mcp桥

适用于任何MCP客户端：Claude Code、Gemini CLI、Cursor、Windsurf、VS Code或任何讲MCP的工具。

你需要这个吗？

如果您在具有shell访问权限的终端代理（Claude Code、Codex CLI、Gemini CLI）中，请直接调用Codex CLI。它更快、更便宜、零开销：

# Review current branch vs main
codex review --base main

# Review uncommitted changes
codex review --uncommitted

# Review with custom focus
codex review --base main "Focus on security and error handling"

# From a worktree (run inside the worktree; `-C` is broken for `review`)
cd /path/to/worktree && codex review --base main

# General analysis
codex exec "Analyze src/utils/parse.ts for edge cases"

在以下情况下使用此MCP网桥：

• 您的客户端没有shell访问权限（Cursor、Windsurf、Claude Desktop、VS Code）
• 您需要具有JSON模式验证的结构化输出（Codex CLI --json 有 已知Bug)
• 您需要在超时时捕获部分响应，并在超时时自动回退模型

配额用尽

• 你想要子进程隔离：显式的env allowlist，没有shell转义，

输出上的秘密编辑、FIFO排队并发（最多3个并行生成， 可通过以下方式配置 CODEX_MAX_CONCURRENT)

• 您需要通过会话恢复进行多轮对话(sessionId /

resetSession，通过以下方式检查 listSessions)

工作树说明：Codex CLI问题 #9084 休息 codex -C /path review ....快跑 codex review 从工作台内部避免它。

快速开始

npx codex-mcp-bridge

先决条件

• Codex CLI 已安装(npm i -g @openai/codex)
• OPENAI_API_KEY 环境变量集，或 codex auth login 完成

克劳德代码

claude mcp add codex-bridge -- npx -y codex-mcp-bridge

Gemini CLI

添加 ~/.gemini/settings.json:

{
  "mcpServers": {
    "codex-bridge": {
      "command": "npx",
      "args": ["-y", "codex-mcp-bridge"]
    }
  }
}

光标/风帆/VS代码

添加到MCP设置中：

{
  "codex-bridge": {
    "command": "npx",
    "args": ["-y", "codex-mcp-bridge"],
    "env": {
      "OPENAI_API_KEY": "sk-..."
    }
  }
}

工具

法典

通用执行。通过以下方式支持多回合对话 sessionId，沙盒级别(read-only, workspace-write, full-auto)以及推理努力控制。通过 resetSession: true 丢弃并重新开始。使用 listSessions 在恢复之前检查活动会话。

关键参数： prompt （必填）， files, model, sessionId, sandbox, reasoningEffort, workingDirectory, timeout （默认60秒）。

搜索

通过Codex CLI由OpenAI的原生搜索基础设施提供支持的Web搜索 --search 旗帜。返回带有源URL的合成答案。

关键参数： query （必填）， model, workingDirectory, timeout （默认120秒）。

查询

轻量级、非代理文本分析。在隔离的临时目录中生成，这样桥的repo上下文就不会泄漏。传递文本以在中进行分析 context 参数。支持 reasoningEffort 和 maxResponseLength.

关键参数： prompt （必填）， context, model, reasoningEffort, timeout （默认60秒）。

审查

Codex CLI的原生差异感知审查的薄包装。桥接器将差速器选择器传递给 codex exec review --json上游食品法典委员会拥有审查提示。需要一个真正的git仓库 workingDirectory.

关键参数： mode （必填： uncommitted, base，或 commit), workingDirectory （必填）， base （需要 base 模式）， commit （需要 commit 模式）， title, model, timeout （默认180秒）。

结构化的

在提示中嵌入JSON模式，并使用Ajv验证响应。成功时返回干净的JSON，失败时返回验证错误。

关键参数： prompt （必填）， schema （必填，JSON字符串）， files, model, workingDirectory, timeout （默认60秒）。

拼

没有参数。返回CLI版本、身份验证状态、模型配置和并发诊断(activeCount, queueDepth).

所有工具都附加执行元数据(_meta)与 durationMs, model, fallbackUsed，以及会话信息（如适用）。看 设计.md 了解详情。

使用此CLI进行代码审查

此桥不捆绑审阅者提示。代码审查有三种途径：

原生上游 codex review

codex review --base main
codex review --uncommitted
codex review --base main "Focus on security and error handling"

Codex CLI内置了差异感知审查。没有桥梁参与。当您的客户端具有shell访问权限时使用此选项。

桥 review 用于本地差异感知审查的工具

{
  "tool": "review",
  "arguments": {
    "mode": "base",
    "base": "main",
    "workingDirectory": "/path/to/worktree"
  }
}

桥在运行 codex exec review --json 从 workingDirectory，捕获最终审阅文本，并返回审阅元数据，例如 threadId、事件计数和已编辑的命令输出。它不接受提示。

桥 codex 带有呼叫者提供的提示的工具

{
  "tool": "codex",
  "arguments": {
    "prompt": "",
    "sandbox": "read-only"
  }
}

桥在运行 codex exec --sandbox read-only 使用提供的提示符并返回stdout。将其用于自由形式的审阅提示或无法表达为的审阅输入 uncommitted, base，或 commit diff选择器。

代表评审提示

起点；自由适应：

Review the following diff:

Look for:
- Bugs that would surface in production
- Missing error handling on user-supplied input
- Tests modified to silence failures rather than verify behaviour
- Security issues (injection, missing auth checks, secret leaks)

For each finding cite file:line, severity (high/medium/low), and a suggested fix.
Skip style/formatting; assume an autoformatter handles those.

该桥对即时内容没有意见。看 ADR-001 理由。

配置

选择Codex MCP服务器

演出

Codex CLI的启动开销最小（\<100ms），因此壁时间主要由模型推理决定。

默认超时（60-300s）对于典型的工作负载来说是舒适的。

Bridge家族

三个MCP服务器，相同的架构，不同的底层CLI。每个都将终端代理包装为子流程，并将其作为MCP工具公开。选择与您的模型提供者匹配的一个，或运行多个跨模型工作流。

|---|---|---|---| | 命令行界面 |Codex CLI |克劳德代码| Gemini CLI| | 提供者 |OpenAI |人类学|谷歌| | 工具 |codex、review、搜索、查询、结构化、ping、listSessions |查询、review，搜索、结构化、ping、listSessions|查询、review、搜索、结构化，ping、fetchChunk| | 代码审查 | review 工具包装原生 codex exec review --json，或 codex 带有呼叫者提供的提示的工具| review 具有调用者提供的提示和强化隔离默认值的工具| review 具有呼叫者提供的提示和强化默认值的工具| | 结构化输出 |Ajv验证|本机 --json-schema |Ajv验证| | 会话恢复 |多回合会话ID |本机 --resume |不支持| | 预算上限 |不支持|本机 --max-budget-usd |不支持| | 努力控制 | reasoningEffort （低/中/高）| --effort low/medium/high/max |不支持| | 冷启动 |\<100ms（推理占主导地位）|~1-2s|~16s| | 认证 | OPENAI_API_KEY | claude login （订阅）或 ANTHROPIC_API_KEY | gemini auth login | | 成本 |每个代币支付|订阅（包括在内）或API信用额度|可用的免费等级| | 并发 |3（可配置）|3（可设置）|3| | 模型回退 |使用回退模式自动重试|使用回退模式手动重试|使用后退模式自动重试|

所有三个共享：子进程环境隔离、路径沙盒、FIFO并发队列、MCP工具注释、， _meta 响应元数据、进度心跳。codex和claude桥还执行输出编校（秘密剥离）。

发展

npm install
npm run build        # Compile TypeScript
npm run dev          # Watch mode
npm test             # Run tests
npm run lint         # ESLint
npm run typecheck    # tsc --noEmit

进一步阅读

• 设计.md -架构、MCP服务器控制语法、会话、输出解析、响应元数据
• 安全.md -环境隔离、路径沙盒、输出编校、资源限制
• 更改日志.md -发布历史

许可证

麻省理工学院