Codex MCP 怎么配置？从第一个 Server 到 OAuth、权限和安全回滚
AI Code With · Codex 实用教程
第一次打开 Codex 的 MCP 配置，很多人都会有一种感觉：我只是想让 Codex 多用一个工具，为什么突然冒出来这么多东西？
MCP Server、STDIO、Streamable HTTP、OAuth、config.toml、工具权限、环境变量……如果一开始就想着把这些全部搞懂，十有八九会越配越乱。
我更推荐另一种做法：先不要追求“配置完整”，先跑通一个最小闭环。
第一次只完成三件事：Codex 能看到一个 MCP Server；Codex 能成功调用一个只读工具；你知道怎么把它关掉或撤回来。
只要这条链跑通，后面的 OAuth、写权限、多 Server 和复杂认证，本质上都是在这个基础上增加复杂度。
先用一句人话解释：MCP 到底是干什么的？
MCP，全称 Model Context Protocol。名字看起来挺技术，但如果你只是使用 Codex，可以先把它理解成：MCP 是 Codex 和外部工具之间的一套连接方式。
Codex 本身擅长读代码、改文件、执行命令、分析项目，但现实中的工作远不止这些。比如你可能希望 Codex 查最新开发文档、读取内部知识库、查询数据库、操作浏览器、访问 GitHub 或项目管理系统，甚至调用公司自己的 API。
这时候就可以通过 MCP Server，把这些能力暴露给 Codex。
Codex
↓
MCP
↓
外部工具 / 数据 / 服务
重要边界：MCP 解决的是“Codex 能使用什么工具”，不是“Codex 用哪个大模型”。
第一步：先分清 STDIO 和 Streamable HTTP
当前 Codex MCP 主要支持两类 Server：STDIO 和 Streamable HTTP。不用一开始研究协议细节，先这样记：STDIO = Codex 在你电脑上启动一个程序；Streamable HTTP = Codex 去连接一个远程地址。
STDIO：适合本地运行的 MCP Server
例如一个 Server 通过 Node.js 包运行：
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
意思其实很简单：Codex 需要这个工具的时候，就启动 npx -y @upstash/context7-mcp 这个本地进程。
Streamable HTTP：适合远程服务
例如：
[mcp_servers.example]
url = "https://example.com/mcp"
这时候 Codex 不负责启动本地程序，而是访问这个 URL。现实中可以粗略理解为：本地文档工具通常更像 STDIO，公司内部远程服务或在线 SaaS MCP 通常更像 Streamable HTTP。
两种方式没有谁更高级，关键是你的 MCP Server 实际运行在哪里。
第二步：第一次别手改太多配置，直接跑一个最小示例
如果你只是第一次尝试 MCP，我反而建议先用 CLI 添加 Server。以 Context7 为例：
codex mcp add context7 -- npx -y @upstash/context7-mcp
执行完以后，第一件事不是马上让 Codex 干活，而是检查：
codex mcp list
如果你已经进入 Codex TUI，也可以输入：
/mcp
查看当前活跃的 MCP Server。
到这里先别高兴：出现在列表里，不代表它真的能用
比如你运行 codex mcp list，看到了 context7，于是觉得“配好了”。其实你现在只证明了一件事：Codex 已经读到了这份配置。
你还没有证明 Server 进程真的能启动、它真的暴露出了工具、Codex 有权限调用，以及工具调用能正常返回结果。
“出现在列表”只代表配置被加载，不代表 Server 已经能正常工作。
第三步：真的调用一次工具
第一次验证，建议刻意选一个只读、无副作用的工具，比如搜索开发文档、查询一条公开信息、读取一个页面或获取某个只读状态。
不要第一次连接成功就让 MCP 删除文件、修改数据库、发消息、提交工单或操作生产系统。
原因很简单：如果第一步就允许一个 Server 同时读、写、删，出问题以后你会同时面对“有没有连上、有没有权限、有没有真的改数据”三个问题，排查难度一下就上去了。
先证明能安全地读，再考虑允许写。
MCP 配置到底放在哪里？
Codex 默认会在下面的位置读取 MCP 配置：
~/.codex/config.toml
受信任项目也可以使用项目级配置：
你的项目/.codex/config.toml
全局配置适合什么？
比如文档查询 MCP、浏览器 MCP、通用知识库 MCP 这类你天天都会用的工具，没有必要每个项目重复配置，放在 ~/.codex/config.toml 比较自然。
项目级配置适合什么？
例如一个公司 CRM 项目有专门读取该项目测试数据的 MCP，它只对这个项目有意义，那就可以放在项目/.codex/config.toml。这样换到别的项目时，不会把一堆无关工具一起带过去。
CLI、桌面端和 IDE 共享 MCP 配置时，要注意什么？
同一台机器上的 Codex CLI、桌面端和 IDE 扩展，可能共享同一套 MCP 配置。这意味着你在 CLI 添加了一个 Server，桌面端重启后也可能直接看到。
这也解释了为什么有时候你明明是在终端里改的配置，桌面端重启以后也发生了变化。
改完配置以后，重启对应客户端再验证，不要靠“我感觉它应该读到了”。
第四步：如果是远程 MCP，再处理 HTTP 和认证
如果你的 Server 不在本机，而是一个远程 URL，那么配置会更接近：
[mcp_servers.example]
url = "https://mcp.example.com"
远程 MCP 还可能涉及 OAuth、Bearer Token、HTTP Header、工具审批和超时等。但第一次不要把所有功能一起塞进去，建议先确认 URL，再确认 Server 能访问，然后处理认证，最后再处理工具权限。
OAuth 怎么处理？
如果 MCP Server 支持 OAuth，可以通过：
codex mcp login <server-name>
启动登录流程。比自己复制 Access Token 然后塞进配置文件里靠谱得多。
尤其不要把真实 Access Token 直接写进配置文件再提交到 Git。更稳的做法是让配置引用环境变量，例如概念上：
[mcp_servers.example]
url = "https://mcp.example.com"
bearer_token_env_var = "MY_MCP_TOKEN"
这样配置文件只知道“去哪里找 Token”，而不是直接保存 Token 本身。
第五步：权限别直接开满
MCP 真正进入长期使用以后，权限会比“能不能连上”更重要，因为 MCP 工具的风险差距非常大。
例如“搜索内部文档”和“修改线上数据库”显然不是一个风险等级。第一次接入时更建议读取相对宽松、写入需要确认、删除或高风险操作严格审批。
一个现实中的例子：浏览器 MCP 为什么不能一上来全放行？
假设你给 Codex 接了一个浏览器 MCP，本来的目的只是帮你查几个网页。但这个 Server 同时可能提供打开网页、读取网页、填写表单、点击按钮、上传文件、提交内容等工具。
“打开网页”和“提交表单”显然不是一个风险等级。如果你直接把所有工具设成自动批准，之后 Codex 的一次误判就可能从“帮我看看发布页有什么字段”变成“顺手把内容提交了”。
MCP 权限真正要判断的不是“我信不信 Codex”，而是“这个工具失败以后，最坏能造成什么结果”。
“MCP 能用了”和“模型能用了”是两套系统
很多人一配置 MCP，就顺手把 OpenAI API、Claude API、Kimi、Provider、API Key 和 MCP 全部搅在一起，最后出错时完全不知道是哪层出了问题。
更清晰的结构应该是：
Codex
/ \
/ \
MCP 工具层 模型 Provider 层
↓ ↓
外部工具/数据 模型 API
MCP 回答的是“Codex 能调用哪些外部工具？”，Provider 回答的是“Codex 的模型请求从哪里走？”。
这时候 AI Code With 在哪里？
配置 MCP 并不要求你必须使用 AI Code With。如果你只是 Codex → Context7 MCP → 查询文档，这件事和 AI Code With 没什么直接关系。
但有两类场景会开始相关。
场景一：你本身就在用 AI Code With 作为 Codex 的模型 Provider
这时 MCP 配置依然负责工具，而 AI Code With 负责 Codex 的模型 API 入口。两套系统可以同时存在，但不要混为一个东西。
例如 Context7 连不上，优先查 MCP；如果 Codex 返回 401 且错误 URL 指向 AI Code With，则应该查 Provider、Key 和 Base URL。把两层拆开，排错会清晰很多。
场景二：你的 MCP Server 自己也要调用大模型
比如你自己写了一个 MCP Server：接收一份长文档，调用一个模型做分类，再把结果返回给 Codex。这时候 MCP Server 内部本身又有模型 API 依赖。
Codex
↓
MCP Server
↓
外部模型 API
如果 Server 同时要使用不同模型，可以把 AI Code With 作为统一模型入口之一，而不是每个 Server 分别维护一套 Provider 账户和 Key。
但这依然不是“装 MCP 就必须装 AI Code With”，而是当模型层本来就复杂时，再解决模型层的问题。
第六步：真正有用的 MCP 排错，应该按层查
1. Server 根本不在列表
先运行：
codex mcp list
如果连 Server 都没有，优先检查配置有没有写对、是不是改错了 config.toml、项目级配置是否位于可信项目、配置语法是否有问题，以及客户端是否需要重启。
2. STDIO Server 在列表里，但启动失败
假设配置是：
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
最实用的方法不是继续猜 Codex，而是直接在普通终端先跑：
npx -y @upstash/context7-mcp
如果这条命令自己都跑不起来，比如 command not found、包安装失败、Node 环境异常或网络下载失败，那 Codex 当然也启动不了。
3. HTTP Server 加载了，但访问失败
这时候优先看 URL、网络、代理、DNS 和服务状态。先确认 Server 本身是不是能访问，不要一上来换 OAuth。
4. Server 能连，但 OAuth 报错
再检查是否执行过 codex mcp login、Client ID、Callback URL、授权服务器配置和 OAuth scope。第一次配置的人不需要立即理解所有名词，先根据实际报错往下查就够了。
5. Server 正常，工具却不能调用
检查 Server 是否真的提供这个工具、工具是否被禁用、当前审批策略、所需环境变量，以及工具自己的外部依赖。
6. MCP 工具能跑，但模型报错
那就别继续折腾 MCP，开始查 Model、Provider、API Key、Base URL，以及额度或 API 状态。
第七步：第一次配置，当天就测试一次回滚
很多教程教你怎么装，但很少教你怎么撤。真正进入开发环境以后，能撤回来和能装上去一样重要。
第 1 步：记住原始状态
codex mcp list
把当前 Server 列表记下来，甚至截个图都行，这就是你的基线。
第 2 步：只加一个测试 Server
codex mcp add context7 -- npx -y @upstash/context7-mcp
不要顺手再装三个。
第 3 步：确认它出现
codex mcp list
第 4 步：调用一个只读工具
只证明 Codex → MCP → Tool 这条路径通了。
第 5 步：如果涉及 OAuth，再单独验证登录
codex mcp login <server-name>
第 6 步：再测试禁用或删除
如果当前配置支持 enabled，可以先通过：
[mcp_servers.example]
url = "https://example.com/mcp"
enabled = false
禁用某个 Server，然后再次运行 codex mcp list 看环境是否回到预期状态。如果需要彻底删除 Server，建议先运行 codex mcp --help，确认当前版本提供的删除命令，而不是照抄几个月前的旧教程。
为什么我特别强调“回滚”？
举个现实一点的情况。你今天为了测试浏览器能力加了 Browser MCP，过两天又加 Docs MCP、Git MCP、Database MCP，突然 Codex 启动开始报 MCP startup interrupted。
如果你从来没有测试过怎么停掉某一个 Server，解决方式很可能是一口气删整个配置。
但如果你一开始就知道 Server A 能用、Server B 是新加的、关闭 B 后恢复，那么问题两分钟就能隔离出来。
这才是“最小闭环”真正有价值的地方。
一个完整的第一次配置流程，应该长这样
确认 Codex 正常运行
↓
选择一个简单 STDIO Server
↓
codex mcp add
↓
codex mcp list
↓
/mcp
↓
调用一个只读工具
↓
检查权限
↓
禁用 / 回滚
↓
再次检查 list
跑通以后，再逐渐加远程 HTTP、Bearer Token、OAuth、写操作工具、项目级 MCP 和多个 MCP Server，而不是反过来。
新手最常见的 7 个误区
| 现象 | 真正应该先查什么 |
| Server 不在列表 | config.toml、配置范围、语法 |
| Server 在列表但启动失败 | STDIO 命令本身能否运行 |
| HTTP MCP 连不上 | URL、网络、服务状态 |
| OAuth 失败 | login 流程、Client / Callback |
| 工具显示但不能执行 | 工具权限、环境变量、审批 |
| Codex 模型请求 401 | Provider / Key / Base URL，不要先怪 MCP |
| 加完 MCP 环境变乱 | 关闭新 Server，恢复到基线逐个排查 |
什么时候才值得把 MCP 配得更复杂？
如果你现在只是想让 Codex 查一份文档，一个简单连接已经够了。没有必要为了显得“专业”立刻上 OAuth、10 个 Server、自动写权限、多环境配置、复杂 Header 和远程 MCP。
真正应该增加复杂度的时机，是需求出现以后：
• 需要公司 SaaS 数据，再上 OAuth。
• 一个 MCP 只适合一个项目，再用项目级 .codex/config.toml。
• Server 有危险写操作，再细分工具审批。
• MCP Server 自己需要调用多个模型，再考虑独立的模型 Provider 管理。
• 多客户端都需要同一个 MCP，再利用共享配置机制，而不是重复维护。
复杂度应该是需求推着你增加，而不是“官方支持，所以我都配上”。
最后：配置 Codex MCP，真正要学的是“分层”
第一次用 MCP，最容易犯的错不是 TOML 写错，而是把所有东西看成一个问题。其实可以拆成七层：
1. Codex 有没有加载 MCP Server？
2. MCP Server 能不能启动或连接？
3. 认证有没有通过？
4. 工具有没有暴露？
5. Codex 有没有权限调用？
6. 工具执行结果对不对？
7. 如果还涉及模型 API，Provider 是否正常？
一层一层查，你就不会再陷入“到底是 MCP 坏了，还是 Codex 坏了，还是 OAuth 坏了，还是 API Key 坏了？”这种状态。
第一次最值得完成的目标依然只有三个：能看到、能调用、能撤回。
如果你同时在给 Codex 配模型
如果你的下一步不是增加 MCP 工具，而是想让 Codex 接不同模型，那么建议把这件事单独处理。AI Code With 提供 Codex 的独立接入配置和统一模型 API 入口，这属于 Provider / 模型层，不是 MCP 层。
MCP
→ 管工具
AI Code With / 其他 Provider
→ 管模型 API
这样以后不管是工具调用失败，还是模型返回 401，你都知道应该先查哪一边。
如果你本来就准备通过 AI Code With 接 Codex，可以先从对应的 Codex 配置文档开始，再回来配置 MCP，不需要把两件事情写进同一套配置里。
相关阅读
• Codex MCP Server 在列表里但不能用，怎么排查
• Codex config.toml 配置完整指南
• Codex 权限与 Approval 怎么设置
• Codex Provider 怎么切换
• Codex 接 AI Code With 完整配置
• Codex 401 Unauthorized 排错
参考资料
OpenAI Codex MCP：https://developers.openai.com/codex/mcp
AI Code With Codex CLI 文档：https://docs.aicodewith.ai/zh/docs/codex-cli
AI Code With 官网：https://aicodewith.ai/zh
