MCP 集成

MCP（Model Context Protocol） 是连接 Codex 与外部系统的标准协议。仓库内的文件操作由 Codex 内置工具完成；Issue 跟踪、设计稿、内部文档、浏览器 等通常通过 MCP 接入。

架构角色

Codex (Host / Client)
        │
        ├── 内置工具：读写文件、Shell（沙箱内）
        │
        └── MCP Servers
              ├── GitHub（PR、Issue）
              ├── Linear / Jira
              ├── 浏览器 / Playwright
              └── 自定义内部 API

MCP Server 可暴露：

Tools — 可调用动作
Resources — 可读数据
Prompts — 可复用提示模板

配置文件

用户级：~/.codex/config.toml
项目级：.codex/config.toml（需 trust 项目 后加载）

典型 stdio 服务器

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "${GITHUB_PERSONAL_ACCESS_TOKEN}" }
enabled = true

HTTP / Streamable HTTP

[mcp_servers.openai_docs]
url = "https://developers.openai.com/mcp"
transport = "streamable_http"
enabled = true

具体字段以 Configuration Reference 为准；不同 transport 字段略有差异。

安全：allowlist

企业场景可限制仅允许特定 MCP：

# 仅启用白名单内的 server 及匹配的身份
allowed_mcp_servers = ["github", "linear"]

未在白名单或未通过身份校验的服务器会被禁用。

与 Skills 配合

反模式： 在 AGENTS.md 里写长篇「如何调 GitHub API」
推荐： Skill 定义流程 + MCP 提供 create_issue、list_prs 等工具

Skill 的 agents/openai.yaml 可声明 MCP 依赖，便于 App 内一键安装。

常见场景

场景	MCP 方向
PR 审查评论	GitHub MCP
ticket → 代码	Linear / Jira MCP
查最新框架文档	官方 docs MCP 或 Firecrawl 类工具
E2E 调试	浏览器 MCP

从 Claude Code 迁移

Claude Code 使用 JSON（如 mcp-servers.json）；Codex 使用 TOML。逻辑相同，需改写结构与键名。官方提供 Migrate to Codex 指南。

调试技巧

先在终端单独启动 MCP server，确认 token 与端口
在 Codex 中用只读任务测试：列出我分配的 open issues
失败时检查 config.toml 的 enabled 与 required 标志

下一步

Subagents 子代理：专责 Agent + 专用 MCP 组合
Agent Skills：在 Skill 中引用 MCP 工具名

#MCP 集成

#架构角色

#配置文件

#典型 stdio 服务器

#HTTP / Streamable HTTP

#安全：allowlist

#与 Skills 配合

#常见场景

#从 Claude Code 迁移

#调试技巧

#下一步