10 · MCP 与外部工具

📚 系列导航：上一篇 09 AGENTS.md 指南教你把项目规矩写进 Codex 的记忆。这一篇给 Codex 接上外部世界。

01 MCP 是什么

Codex 默认只能摸你本地的文件和命令。MCP（Model Context Protocol）就是那个统一外接口——接一次，一堆外部服务的工具就摆到了它面前。

判断标准： 当你发现自己从另一个工具复制数据到聊天中时，就该接 MCP 了。

MCP 不是 OpenAI 的私有协议，而是一套公开规范。同一个 MCP server，Codex 能用，Claude Code 也能用。只是配法不同——下面专门讲差异。

TIP

Codex 会读 server 初始化时返回的 instructions 字段，当成这个 server 的「使用须知」——好的 server 自带一份说明书，Codex 会一并读进去。

02 两种 server 形态

形态	跑在哪	怎么加	适合
STDIO（本地进程）	你机器上，作为子进程启动	`codex mcp add <name> -- <command>`	本地工具，需本地有对应环境
Streamable HTTP（远程托管）	某个网址上	`codex mcp add --transport http <name> <url>`	云服务，推荐

STDIO 的精髓是那条「启动命令」——Codex 帮你在后台拉起一个进程。所以它能跑的前提是你机器上有对应环境（如 npx 需要 Node.js）。STDIO 还能单独传环境变量（--env 或配置里的 env）。

HTTP 的鉴权方式有两种：

Bearer token：在配置里指定存 token 的环境变量名（bearer_token_env_var），token 本身不进配置文件
OAuth：在终端跑 codex mcp login <server-name> 走授权流程

03 配置方式

Codex 所有 MCP 配置都在 config.toml 里。关键区别：Codex 没有 --scope 参数。 作用范围靠配置文件放在哪决定：

配置写在哪	在哪些项目生效
`~/.codex/config.toml`（全局）	你所有项目
项目里的 `.codex/config.toml`	仅当前项目（且需是受信任项目）

NOTE

CLI 和 IDE 扩展共用这份配置。你在终端配好的 MCP server，切到 VS Code 里的 Codex 扩展直接用。

方式一：命令式（最快）

bash

codex mcp add <server-name> -- <stdio 启动命令>
codex mcp add --transport http <name> <url>

方式二：手写 config.toml（更细）

toml

# STDIO server
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

# HTTP server with Bearer token
[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"

04 收口一个 server

字段	作用	默认值
`enabled`	临时禁用	`true`
`enabled_tools`	工具白名单	不写则全放
`disabled_tools`	工具黑名单（在白名单之后应用）	—
`default_tools_approval_mode`	该 server 工具的默认审批行为	`auto` / `prompt` / `approve`
`startup_timeout_sec`	server 启动超时	`10` 秒
`tool_timeout_sec`	单次工具调用超时	`60` 秒

白名单优先于黑名单： disabled_tools 是在 enabled_tools 之后应用。先圈出允许的工具，再从里剔掉个别危险的。

toml

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
disabled_tools = ["screenshot"]          # 最终只剩 open
default_tools_approval_mode = "prompt"   # 默认每次问我
startup_timeout_sec = 20                 # 启动慢的调大

05 安全

WARNING

MCP server 是第三方代码，OpenAI 不替你审计。接之前先验证信任。

几条土规矩：

官方文档点名推荐的（Context7、Figma、Playwright）→ 相对放心
大厂官方出的（GitHub、Sentry） → 相对放心
GitHub 上 star 不多的第三方 server → 先看源码再接入
陌生 server 的工具默认设 prompt，危险工具用 disabled_tools 拦死
给数据库只用只读账号
抓外部内容的 server 当心提示注入——网页里可能藏恶意指令

06 动手：接 Context7 文档 server

bash

codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp list

预期：context7 旁边标 ✓ Connected。在 Codex 会话里：

text

用 context7 查一下 TypeScript 5.0 的新特性

练完拆掉：codex mcp remove context7

07 小结

环节	关键动作
加 server	STDIO 给命令，HTTP 给 URL
作用域	没 `--scope`，靠配置文件位置决定
收口	`enabled` / `enabled_tools` / `disabled_tools` / `default_tools_approval_mode`
超时	启动默认10s，工具调用默认60s
HTTP 鉴权	Bearer token（只写变量名）或 OAuth
安全	优先官方，数据库只读，陌生 server 收紧审批

NOTE

下一篇：11 Subagent 与多 Agent 协作：派分身干脏活，让主会话保持清爽。

10 · MCP 与外部工具 ​

01 MCP 是什么 ​

02 两种 server 形态 ​

03 配置方式 ​

方式一：命令式（最快） ​

方式二：手写 config.toml（更细） ​

04 收口一个 server ​

05 安全 ​

06 动手：接 Context7 文档 server ​

07 小结 ​