Codex 够不到外部世界,先给它装个 USB-C 口
你兴冲冲装好 OpenAI Codex,让它用某个库写段代码,它给出的 API 是一年前的旧写法,跑不通。你让它去看看 GitHub 仓库里那个报错的 issue,它直接告诉你,访问不了。
这不是它笨。Codex 默认只有两样输入,训练时记住的知识,加上你本地的文件。训练知识会过时,本地文件够不到外部世界。
MCP 就是来补这条缝的,全名模型上下文协议。协议细节你不用管,先记住一个画面,它是 AI 的 USB-C 口。以前每接一个外部工具都要单独写一套接入代码,查 GitHub 一套,抓网页又一套。现在一个标准接口,Codex、Claude Code、Cursor 这些支持 MCP 的工具都能接上同一批服务器。装上它,Codex 就有了第三条输入通道,实时去外部世界取数据。
这篇按动手顺序写,先认角色,再十分钟装好第一个,然后是装机清单、配置字段和安全坑。
先认全三个角色
MCP 的事,拆成三个角色就清楚了。
Codex 是客户端,决定这一步要不要调工具、调哪个。MCP 服务器是接在口子上的工具盒,每个提供一类具体能力,比如查文档、抓网页、连 GitHub。中间还有传输方式的问题,本地走 STDIO,远程走 HTTP,后面细说。
一次典型的调用长这样。你对 Codex 说,用 Context7 查一下 Next.js 最新的路由用法。Codex 自己判断该调 Context7,通过 MCP 协议发请求,Context7 返回最新文档,Codex 把文档读进上下文再回答你。注意是谁在决定调用,是 Codex 自己,不是你手动点。
这带出一个新手常见的误会,装了 MCP 不等于它每次都会用。Codex 是否调用某个服务器,取决于它判断这一步用不用得上。装了却一直没被用,多半不是没装成功,是你的指令太含糊,它没意识到该调。把话说明确,或者在 AGENTS.md 里写一句「遇到查文档就用 Context7」,它就开窍了。
检验自己有没有真懂,三道小题就够。谁决定什么时候调工具,Codex 自己。具体能力谁提供,MCP 服务器,一类一个。配置写在哪、谁负责加载,~/.codex/config.toml,Codex 启动时读。三道都答得上来,后面的配置就只是往正确位置填字段,心里不慌。
为什么第一个该装文档类。AI 写代码翻车的原因五花八门,但按它脑子里那套旧 API 写、结果跑不通,是最高频又最容易被忽略的一类,代码看着对,只是版本对不上。文档类 MCP 正好堵这个口子,还免费不要 Key。
十分钟装好第一个
第一个推荐 Context7,实时拉最新的编程库文档,免费,不要 API Key,用一次就能看到价值。
前提只有一条,本机要有 Node.js 18 以上版本,命令行敲 node -v 确认,很多 MCP 服务器是 npm 包,靠 npx 启动。然后一行命令。
codex mcp add context7 -- npx -y @upstash/context7-mcp
拆开看。codex mcp add 是加一个服务器,context7 是你给它起的名字,之后喊它就喊这个名。关键是那个双横线,它是分隔符,告诉 Codex 后面这段别当成我的参数,是要执行的启动命令。Context7 是本地服务器,所以要带启动命令。远程服务器没有本地命令可启动,改用 --url 直接给地址,同一个命令两种写法,对应两类服务器,不矛盾。
验证也简单。进 Codex 终端敲 /mcp,看到 context7 在活跃服务器列表里就成了,也可以命令行跑 codex mcp list 检查配置写对没。装好后试一句,用 context7 查 React 的 useEffect 最新文档,告诉我清理函数怎么写。它真去拉了文档再回答,握手就算成功。
之后你基本什么都不用做,正常派活就行。比如让它用 Prisma 写个用户表查询,按官方最新写法,它发现自己记的写法可能旧了,自动调 Context7 拉最新文档再动手。该查的时候它自己查,这比你自己开浏览器搜文档、复制粘贴给 AI 强多了。当然你也可以显式点名「用 context7 查」,在它没主动调时强制它走一趟。

清单分两档,装少不装多
新手清单分两档,先把免费不要 Key 的跑顺,再按需加要 Key 的。
第一档两个。Context7 上面装过了。再加一个 OpenAI 官方的文档服务器,搜和读 OpenAI 自家开发文档用。
codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp
按 OpenAI 官方文档的说法,这个服务器是只读的,只查文档,不替你调 OpenAI API。想让 Codex 主动用它,官方建议在 AGENTS.md 里加一句,需要查 OpenAI API 或 Codex 相关内容时用 OpenAI 文档 MCP,不用每次明说。
第二档都要凭据,跑顺前两个再考虑。GitHub MCP 查仓库、issue、PR,要一个访问令牌,添加时用 --bearer-token-env-var 指到存令牌的环境变量,别把令牌明文写进命令。Firecrawl 抓网页和搜索,要 API Key。Playwright 控制浏览器,一般不要 Key。Sentry 读错误日志,要凭据。
先跑顺一个,再加下一个,这条原则贯穿全程。一上来装五个,出了问题你根本分不清是哪个的锅。
还要泼盆冷水,MCP 不是越多越好。每个开着的服务器都会把工具描述注入 Codex 的上下文,哪怕这次任务根本用不上。装十个,它每次对话开头先读十套说明,白吃 token 还分散对真实任务的注意力。Anthropic 工程团队讲 MCP 时也说过,连的服务器太多,工具定义和结果会消耗过多令牌,拖低代理效率。老雷的建议是常用控制在三五个,暂时不用的别删,把 enabled 设成 false 关掉,需要时再打开。
MCP 装一个,等于把一段别人写的、能在你机器上动手的代码请进门。看清来源再装,跟装浏览器插件一个道理。

配置文件一次讲透
Codex 的 MCP 配置都在 ~/.codex/config.toml 里,每个服务器是一个块,CLI 和 IDE 扩展共用这一份,配一次两边生效。用命令装完会自动生成对应块,也可以手写。本地服务器长这样。
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
远程的就两行,块名加 url。字段不用记全,会两件事就够入门。要 Key 的,把 Key 放进 env,远程的则用 bearertokenenv_var 指向一个环境变量,别把明文 Key 直接写进文件。想临时关掉某个服务器又不删配置,enabled 设 false。
传输方式选型有个口诀,本地的事用 STDIO,远程的服务用 HTTP。让 Codex 读本机目录、连本地数据库这类事,用 STDIO,它在你电脑上顺手开一个子进程,数据不出门。查公共文档、调远程 API,用 HTTP,不装本地依赖,提供方负责维护更新。配置上的区别就一点,STDIO 填 command 加 args,HTTP 填 url。
还有几个字段知道就好,碰到再查。startuptimeoutsec 管启动超时,默认 10 秒。tooltimeoutsec 管单次调用超时,默认 60 秒。required 设成 true,启动失败就直接报错,不默默跳过。
安全坑和四步排查
装之前把风险认清,三类主要的。
工具中毒,恶意服务器在工具描述里藏私货,AI 读到会被骗去执行非预期操作,因为工具描述会原样进入模型上下文,它没法天然分辨哪句是说明、哪句是指令。命令注入,安全公司 Endor Labs 分析了 2614 个 MCP 实现,约 34% 用到容易被命令注入的接口,攻击者可能借此在你机器上跑任意命令。配置被偷换,Cursor 编辑器出过真实案例,编号 CVE-2025-54136,老版本只对配置批准一次就长期信任,攻击者事后把同名配置改成恶意命令,每次打开项目静默执行,Cursor 已在 1.3 修复,任何改动都重新弹批准。同类还有影子攻击,恶意服务器伪造已知工具的行为,截走本该发给正版服务器的调用。
老雷给大家提个醒,最常见的翻车起点就是从陌生仓库或聊天群里复制一段配置直接装上跑,根本没看是谁发的。避坑记三件事。只装可信来源,官方 MCP 仓库加大型厂商发布的,陌生个人仓库先存疑。版本钉死,config.toml 里写明确版本号,别无脑用 latest,免得上游哪天被投毒,你自动拉到坏版本。重要项目用 Codex 自带沙箱收权限,别给 MCP 超出需要的文件读写和网络权限。
装了没生效,先别换模型别重装,四步排查。看状态,终端敲 /mcp 或跑 codex mcp list,检查名字、命令、URL 有没有拼错。调超时,启动失败把 startuptimeoutsec 从 10 调到 30,给慢启动的服务器多点时间。查环境变量,要 Key 的服务器确认 Key 的名字和值真填了。让它显式调,直接说用 context7 查什么,它要是说不知道这个工具,说明协议没握上手。最常见的根因是 npx 找不到,回到 Node.js 18 那一步。还查不出来,把 required 设成 true,让启动错误直接报给你看,而不是默默跳过。
最后过一遍自检。Node 18 装了吗。第一个装的是免费不要 Key 的吗。配置在哪、用 /mcp 验证过上线吗。STDIO 和 HTTP 分清了吗。来源可信、版本固定了吗。常用服务器控制在三五个了吗。哪题答不上,回到对应段落再看一眼。
给 Codex 接 MCP,接的是它够不到的外部世界。口子开得越少越稳,每一个都得是你认识的。
从今天第一个 Context7 开始。第一天装好,第一周用顺两三个,一个月后你自然知道自己真正需要哪几个,剩下的关掉就好。到那步再回头看,这条路的回报曲线很清楚,前期花的是十来分钟的配置功夫,换来的是 Codex 从总给旧答案,到能实时取最新数据的转变。
