第 05 章

MCP 外部工具

给 Codex 装上第三只眼——调用外部 API、数据库和自定义工具

从"只能聊天"到"连接一切"

反复切换的痛苦

你正在用 Codex 写代码，却需要不断跳出终端去查外部信息

查文档要切浏览器

Codex 不知道最新的 API 参数，你只能打开官网查完再粘回来——来回切换 20 次。

查数据库要开客户端

你需要确认表结构、字段类型，只能切到 DBeaver 或 pgAdmin，复制粘贴结果。

查日志要登服务器

你想让 Codex 分析线上报错，但它访问不了你的日志平台。每次都要你手动喂数据。

核心矛盾：Codex 模型本身无法联网、无法访问私有系统。它需要一个"手"来触碰外部世界——这就是 MCP。

开始之前

前置知识

已完成第 01 章：能正常启动 Codex CLI
了解 JSON 基本语法（key-value 结构）
对终端命令行有基本认知

学完能做什么

为 Codex 接入实时文档、数据库等外部工具
三种方式配置 MCP server
甚至把 Codex 自身暴露为 MCP server 供其他 agent 调用

本章不覆盖

MCP 协议的底层实现细节（JSON-RPC 2.0 帧格式）
如何从零开发一个 MCP server
OAuth 认证流程（高级 HTTP server 场景）

示例环境：Windows + PowerShell。macOS / Linux 命令语法相同。

MCP 是什么

Model Context Protocol——让 AI 模型调用外部工具的标准化协议

一句话解释

MCP 就像 USB 接口——定义了模型与外部工具之间插拔的统一标准。只要 tool 实现 MCP 协议，任何兼容的 AI client 都能调用它。

三个核心概念

MCP Server：提供外部能力的程序
MCP Client：消费 server 能力的程序（Codex CLI）
Transport：通信方式（stdio 或 HTTP）

三种配置方式

告诉 Codex 去哪里找 MCP server，有三种等价途径

方式一：.mcp.json

放在项目根目录的 JSON 文件。可提交到 Git，团队共享。

my-project/
+-- .mcp.json      <- MCP 配置
+-- AGENTS.md
+-- src/

方式二：config.toml

写在 Codex 配置文件的 [mcp_servers] 段。适合个人全局配置。

方式三：CLI 动态

用 codex mcp add 命令临时添加。不写文件，即时生效，适合快速试用。

.mcp.json 格式

最常用的配置方式——项目级 JSON 文件

{
  "servers": {
    "github": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    },
    "openai-docs": {
      "transport": "http",
      "url": "https://developers.openai.com/mcp"
    }
  }
}

顶层结构

servers 是一个对象，key 就是 server 名称，value 是 transport 配置。Codex 启动时自动读取。

stdio 模式

Codex 启动子进程，通过标准输入输出通信

适用场景

本地安装的工具（npm/pip/apt 安装）
需要访问本机文件系统的 tool
需要环境变量注入的私有 API

配置字段

"transport": "stdio"
"command"：可执行文件路径
"args"：命令行参数数组
"env"：（可选）环境变量

"my-server": {
  "transport": "stdio",
  "command": "node",
  "args": ["./my-mcp-server.js"],
  "env": { "API_KEY": "sk-..." }
}

HTTP 模式

通过网络 URL 连接远程 MCP server

适用场景

公开托管的 MCP 服务（如 OpenAI Docs MCP）
需要在多机器间共享的 server
不想安装本地依赖的场景

配置字段

"transport": "http"
"url"：MCP server 的 HTTPS 端点
"headers"：（可选）自定义请求头

"openai-docs": {
  "transport": "http",
  "url": "https://developers.openai.com/mcp",
  "headers": {
    "Authorization": "Bearer your-token"
  }
}

config.toml 内联

在全局配置中直接声明 MCP server

Codex 支持在 config.toml 中使用 [mcp_servers] 段：

[mcp_servers.github]
transport = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]

[mcp_servers.openai-docs]
transport = "http"
url = "https://developers.openai.com/mcp"

何时选用：Toml 内联适合不想新增 .mcp.json 的场景；.mcp.json 更适合团队共享。两种等价，可同时使用。

CLI 管理命令

用 codex mcp 子命令动态管理 server

命令	作用
`codex mcp add <name> -- <cmd> [args...]`	添加 stdio server
`codex mcp add <name> --url <url>`	添加 HTTP server
`codex mcp list`	列出所有 server
`codex mcp remove <name>`	移除 server

小贴士：-- 是分隔符——之前是 MCP 参数，之后是命令原文透传。

实战：OpenAI Docs

用一个命令让 Codex 实时查阅开发者文档

$ codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp

这行做了什么

注册名为 openaiDeveloperDocs 的 MCP server
使用 HTTP transport 连接官方端点
Codex 启动后自动加载 server 的所有工具

如何使用

启动 Codex 后直接问：

用户：response_format 参数支持哪些类型？

Codex 自动调用 MCP 工具查询最新文档，而非依赖训练数据。

验证已添加

用 list 命令确认 server 注册成功

$ codex mcp list
  openaiDeveloperDocs (http)  connected
    url: https://developers.openai.com/mcp
    tools: query_docs, search_docs

输出解读

connected：server 可达，工具已加载
tools：server 暴露的所有可调用工具

移除不需要的

$ codex mcp remove openaiDeveloperDocs
Removed MCP server: openaiDeveloperDocs

实战：GitHub MCP

让 Codex 直接操作你的 GitHub 仓库

{
  "servers": {
    "github": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_YourTokenHere"
      }
    }
  }
}

安全提醒：Token 不要直接写进 .mcp.json 并提交 Git！

GitHub MCP 能力

接入后 Codex 可以代劳这些操作

issue 管理

列出 open issues
创建新 issue
评论 / 关闭 issue

PR 操作

列出待审核的 PR
查看 diff 和 CI 状态
创建 PR

代码浏览

按关键词搜索代码
查看文件内容
列出目录结构

用户：列出 openai/codex 仓库中带 "bug" 标签的 open issue
Codex：[调用 github MCP list_issues] 找到了 3 个...

Server 级别配置

除了 transport，还有 env、timeout 等字段

"my-server": {
  "transport": "stdio",
  "command": "python",
  "args": ["./server.py"],
  "env": {
    "DATABASE_URL": "postgresql://localhost/mydb"
  },
  "timeout": 30,
  "enabled": true
}

env

注入子进程的环境变量。不共享父进程——只写在这里 server 才能读到。

timeout

单次调用超时秒数，默认 30 秒。复杂查询可调高。

enabled

false 可临时禁用 server 而不删除配置。

过滤生效 Server

只启用当前任务需要的 server

enabled_mcpjson_servers = ["github", "openaiDeveloperDocs"]
# 或排除特定 server
disabled_mcpjson_servers = ["database"]

为什么？工具越多，上下文窗口占用越大，响应越慢。

网络访问权限

HTTP 模式的 server 需要开启网络权限

沙箱环境下

Codex 启用沙箱时默认不开放网络。需要显式允许：

[sandbox_workspace_write]
network_access = true

stdio 不需要

stdio server 在本地执行，网络调用不受沙箱限制。

反向操作：暴露 Codex

把 Codex 自身作为 MCP server 给其他 agent 调用

这是什么

Codex 不仅能当 client，还能反向作为 MCP server——让其他 AI agent 把代码生成当作工具调用。

协议

JSON-RPC 2.0 over stdio。标准协议，任何 MCP client 都能对接。

状态

实验性功能。API 可能变更，适合尝鲜和原型开发。

mcp-server 命令

一行命令启动 Codex MCP server

$ codex mcp-server

输出

通过 stdio 以 JSON-RPC 2.0 帧通信。可管道传给 client：

$ codex mcp-server | your_mcp_client

暴露的工具

codex/exec——执行自然语言任务
codex/status——查询当前会话状态

Python 连接示例

用 Python SDK 连接 Codex MCP server

import asyncio

async def main():
    process = await asyncio.create_subprocess_exec(
        "codex", "mcp-server",
        stdin=asyncio.subprocess.PIPE,
        stdout=asyncio.subprocess.PIPE,
    )
    reader = process.stdout
    # 初始化握手、调用工具...
    response = await reader.read()
    print(f"Codex 暴露的工具: {response}")

asyncio.run(main())

关键思路：Codex 变成另一个 agent 手里的"工具"——这就是 agent 编排的常见模式。

编排场景

把 Codex 嵌入更大的 agent 工作流

代码审查流水线

主 agent 调用 Codex MCP 生成代码，再调用 linter MCP 检查。

自动化运维

编排 agent 调用 Codex MCP 生成修复脚本，经审批后执行。

CI/CD 管道

CI 服务器运行轻量 MCP client，测试失败时调用 Codex 生成修复 PR。

安全注意

MCP server 能做的事，Codex 就能做——谨慎授权

信任已知来源

只添加来自官方库、知名厂商或自己编写的 MCP server。

审查配置

提交 PR 前人工 review server 地址和命令。

最小权限

给 server 的 token 只授予最小必要权限。

红线：永远不要将 admin 密钥放进 .mcp.json 并提交 Git。

连接更稳了

0.146：认证变化时刷新，健康连接不中断

认证变了自动刷新

当你重新登录、token 轮换或切换账号时，MCP 连接和 Apps 工具会自动刷新，不用手动重启每个 server。

健康连接不断

重连机制现在不中断仍在健康的连接——只重建出问题的那部分，避免"一个 server 抖动，全部重连"。

实际影响：长会话里偶尔的认证过期、网络波动，不再让所有 MCP 工具集体掉线。你大概率感知不到这次改进——因为本来该报错的地方，现在静默恢复了。

常见错误

server 启动失败？先排查这些

启动失败

原因：command 路径错误或依赖未安装。

修复：终端直接运行 command + args。

$ npx -y @modelcontextprotocol/server-github

transport 错误

原因：写了 tcp 或其他无效值。

修复：只允许 stdio 或 http。JSON key 不要拼错。

常见错误 (2)

PATH 环境问题

原因：子进程找不到 npx / node / python。

修复：在 env 中显式指定 PATH。

HTTP 连接超时

原因：URL 不可达、网络受限。

修复：先用 curl -I 测试。确认是否要 network_access = true。

综合示例

多 server 混合配置

{
  "servers": {
    "github": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "$GH_TOKEN" }
    },
    "openai-docs": {
      "transport": "http",
      "url": "https://developers.openai.com/mcp"
    },
    "notion": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@mcp/server-notion"],
      "enabled": false
    }
  }
}

要点：混合 stdio + HTTP；用 enabled: false 临时禁用；$GH_TOKEN 引用环境变量。

调试技巧

server 出了问题怎么排查

单独运行 server

先脱离 Codex，终端直接运行 command + args。

$ npx -y @modelcontextprotocol/server-github

查看详细日志

[logging]
level = "debug"

验证 JSON 合法

一个多余逗号就导致全部不加载。

$ python -m json.tool .mcp.json

MCP 生态

可用 server 远不止这两个

官方集合

modelcontextprotocol/servers 维护数十个官方实现：数据库、浏览器、Git、Slack 等。

社区贡献

越来越多公司发布自己的 MCP server。任何 HTTP API 都可以包装。

自建 server

用 Python mcp 包或 TypeScript SDK 几行代码就能创建。

CLI vs 文件

什么时候用哪种方式

场景	推荐方式	理由
团队项目	.mcp.json	可提交 Git 共享
个人全局	config.toml	所有项目都能用
快速试用	codex mcp add	一行命令，不留痕
排除/过滤	config.toml	enabled/disabled 列表

动手练习

三步完成你的第一个 MCP 接入

试一个试

$ codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp

改一个改

创建 .mcp.json，加入 GitHub MCP server。单独运行确认。

查一个查

启动 Codex，问一个你不确定的问题。观察是否自动查询。

进阶阅读

想深入了解 MCP 生态？从这里开始

官方协议规范

modelcontextprotocol.io——完整规范文档。

官方 Server 列表

github.com/modelcontextprotocol/servers——精选 server 实现。

自建 Server 教程

modelcontextprotocol.io/quickstart——5 分钟用 Python 创建。

本章回顾

核心概念

MCP = Model Context Protocol
Server / Client / Transport 三件套
两种 transport：stdio + HTTP

三种配置

.mcp.json——项目级
config.toml——全局内联
codex mcp add——CLI 动态

独特亮点

codex mcp-server 反向暴露
enabled/disabled 过滤
HTTP 需 network_access

第 05 章

小结

Codex 不再只是终端里的对话框——它是一个连接外部世界的节点

本章要点

MCP 让 Codex 调用外部工具（stdio / HTTP）
三种配置方式：.mcp.json / config.toml / CLI 命令
用 codex mcp-server 反向暴露 Codex 给其他 agent
安全第一：最小权限、审查配置、不硬编码密钥

下一步：第 06 章 Agent Plugins —— MCP 是单点工具连接，Plugins 则把 MCP、Skills、AGENTS.md 打包成一个可分享、可迁移的能力包。

MCP 外部工具

反复切换的痛苦

你正在用 Codex 写代码，却需要不断跳出终端去查外部信息

查文档要切浏览器

查数据库要开客户端

查日志要登服务器

开始之前

前置知识

学完能做什么

本章不覆盖

MCP 是什么

Model Context Protocol——让 AI 模型调用外部工具的标准化协议

一句话解释

三个核心概念

MCP 架构示意

三种配置方式

告诉 Codex 去哪里找 MCP server，有三种等价途径

方式一：.mcp.json

方式二：config.toml

方式三：CLI 动态

.mcp.json 格式

最常用的配置方式——项目级 JSON 文件

顶层结构

stdio 模式

Codex 启动子进程，通过标准输入输出通信

适用场景

配置字段

HTTP 模式

通过网络 URL 连接远程 MCP server

适用场景

配置字段

config.toml 内联

在全局配置中直接声明 MCP server

CLI 管理命令

用 codex mcp 子命令动态管理 server

实战：OpenAI Docs

用一个命令让 Codex 实时查阅开发者文档

这行做了什么

如何使用

验证已添加

用 list 命令确认 server 注册成功

输出解读

移除不需要的

实战：GitHub MCP

让 Codex 直接操作你的 GitHub 仓库

GitHub MCP 能力

接入后 Codex 可以代劳这些操作

issue 管理

PR 操作

代码浏览

Server 级别配置

除了 transport，还有 env、timeout 等字段

env

timeout

enabled

过滤生效 Server

只启用当前任务需要的 server

网络访问权限

HTTP 模式的 server 需要开启网络权限

沙箱环境下

stdio 不需要

反向操作：暴露 Codex

把 Codex 自身作为 MCP server 给其他 agent 调用

这是什么

协议

状态

mcp-server 命令

一行命令启动 Codex MCP server

输出

暴露的工具

Python 连接示例

用 Python SDK 连接 Codex MCP server

编排场景

把 Codex 嵌入更大的 agent 工作流

代码审查流水线

自动化运维

CI/CD 管道

安全注意

MCP server 能做的事，Codex 就能做——谨慎授权

信任已知来源