Codex As Mcp

codex-as-mcp

中文版

codex-as-mcp 是一个小型 Model Context Protocol (MCP) 服务，可让 MCP 客户端（Claude Code、Cursor 等）将工作委托给 Codex CLI。

它提供两个工具，可在服务当前工作目录中运行 Codex：

• spawn_agent(prompt: str)
• spawn_agents_parallel(agents: list[dict])

在底层，每个 Agent 都会运行类似以下的命令： codex exec --cd <server cwd> --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox -。

提示词通过 stdin 发送，随后关闭 stdin。这样可以避免命令行引号和长度问题，并防止 Codex 意外地从 MCP 服务的 JSON-RPC stdin 管道读取内容。

注意：--dangerously-bypass-approvals-and-sandbox 会禁用沙盒和确认提示。仅在你信任的仓库中使用此服务。

在 Claude Code 中使用

codex-as-mcp 中有两个工具

你可以使用提示词并行生成多个 Codex 子 Agent。

以下是一个 Codex 会话同时委托两项任务的示例。

快速开始

1. 安装 Codex CLI

需要 Codex CLI >= 0.46.0

npm install -g @openai/codex@latest
codex login

# Verify installation
codex --version

确保 Codex CLI 可以在你的机器上以非交互方式运行（在 ~/.codex/config.toml 中配置提供方和凭据，或通过其中引用的特定提供方环境变量配置）。

示例：第三方提供方 + env_key

如果你使用第三方提供方，请在 Codex config.toml 中进行配置，并将 model_provider 指向该提供方。当提供方使用 env_key 时，Codex CLI 运行时需要能够访问该环境变量。

示例：

model_provider = "custom_provider"

[model_providers.custom_provider]
name = "custom_provider"
base_url = "https://..."
wire_api = "responses"
env_key = "PROVIDER_API_KEY"
show_raw_agent_reasoning = true

使用 codex-as-mcp 时，确保 MCP 服务进程已设置该环境变量，以便将其传递给启动的 codex 进程。环境变量名称必须与上述 env_key 值一致（此处为：PROVIDER_API_KEY）。

选项 A（推荐）：在 MCP 客户端配置中设置环境变量（如果支持）

{
  "mcpServers": {
    "codex-subagent": {
      "type": "stdio",
      "command": "uvx",
      "args": ["codex-as-mcp@latest"],
      "env": {
        "PROVIDER_API_KEY": "KEY_VALUE"
      }
    }
  }
}

选项 B：通过服务参数传递环境变量

uvx codex-as-mcp@latest --env PROVIDER_API_KEY=KEY_VALUE

选项 C：通过 Codex CLI 添加（codex mcp add）

codex mcp add codex-subagent --env PROVIDER_API_KEY=KEY_VALUE -- uvx codex-as-mcp@latest

安全提示：通过命令行参数传递密钥可能会在你机器的进程列表中显示；如有可能，请优先选择选项 A。

2. 配置 MCP

添加到你的 .mcp.json：

{
  "mcpServers": {
    "codex-subagent": {
      "type": "stdio",
      "command": "uvx",
      "args": ["codex-as-mcp@latest"]
    }
  }
}

或使用 Claude Desktop 命令：

claude mcp add codex-subagent -- uvx codex-as-mcp@latest

如果要直接配置 Codex CLI（例如 ~/.config/codex/config.toml），请添加：

[mcp_servers.subagents]
transport = "stdio"
command = "uvx"
args = ["codex-as-mcp@latest"]
# Increase if you see ~60s tool-call timeouts when running longer Codex tasks.
# tool_timeout_sec = 600

工具

• spawn_agent(prompt: str) – 使用服务的工作目录启动一个自主 Codex 子 Agent，并返回该 Agent 的最终消息。
• spawn_agents_parallel(agents: list[dict]) – 并行启动多个 Codex 子 Agent；每个条目都必须包含 prompt 键，每个 Agent 的结果中包含 output 或 error。

维护者实时冒烟测试

默认 CI 使用单元测试和模拟子进程路径，因此无需凭据即可安全运行。维护者还可以通过设置仓库密钥 CODEX_LIVE_API_KEY，并在工作流输入中提供兼容 Responses 的 base_url/model，手动触发使用真实提供方的 Live Codex smoke GitHub Actions 工作流。

注意：当前 Codex CLI 会拒绝 wire_api = "chat"；仅支持 chat-completions 的提供方（例如直接使用 DeepSeek API）需要 Codex 原生支持该 wire API，或使用兼容 Responses 的代理。

故障排除

spawn_agent 在约 60 秒后超时

如果你看到类似以下错误：

tool call failed for `subagents/spawn_agent`
timed out awaiting tools/call after 60s
deadline has elapsed

这通常是客户端侧 MCP 工具调用超时。spawn_agent 会等到启动的 codex exec 进程结束后才返回，而这可能需要超过 60 秒。

解决方法：在 MCP 客户端中增加工具调用超时时间。

Codex CLI

在 Codex 配置文件（~/.codex/config.toml 或 ~/.config/codex/config.toml）中，为 MCP 服务设置更高的 tool_timeout_sec：

[mcp_servers.subagents]
transport = "stdio"
command = "uvx"
args = ["codex-as-mcp@latest"]
tool_timeout_sec = 600

MCP Inspector / mcp dev

如果你使用 MCP Inspector 进行本地测试，请增加请求超时时间（或运行会导出这些设置的 ./test.sh）：

export MCP_SERVER_REQUEST_TIMEOUT=300000
export MCP_REQUEST_TIMEOUT_RESET_ON_PROGRESS=true
export MCP_REQUEST_MAX_TOTAL_TIMEOUT=28800000