Codex MCP 教程：添加、配置、登录与安全使用
更新日期：2026 年 10 月 24 日。本文根据 OpenAI Codex 官方仓库和 2026 年 10 月本机
codex mcp --help整理。具体 MCP 服务的能力、授权和配置由对应服务商决定。
MCP（Model Context Protocol）是一套让 AI 客户端连接外部工具和数据源的协议。对 Codex 来说，MCP 可以让它访问文档、问题追踪、数据库或内部业务服务，也可以把外部操作暴露成可调用工具。它扩展的是“能访问什么、能做什么”，所以配置之前要先判断这个连接是否真的必要。
普通代码修改、运行测试和阅读仓库通常不需要 MCP。第一次使用 Codex，建议先把 Codex 使用教程总览 中的本地流程跑通，再按任务增加外部连接。
MCP 能做什么，不能做什么
适合的用途包括：
- 从已授权的文档服务读取最新接口说明；
- 查询项目管理工具中的任务和评论；
- 通过受控接口查看日志、监控或业务数据；
- 连接内部服务，并把操作限制在指定工具与权限范围内。
MCP 不能自动解决三件事：
- 不能证明服务可信。 名称看起来像官方服务也可能不是。先核对域名、发布者、仓库与组织政策。
- 不能替代最小权限。 一个服务器暴露的工具很多，不代表当前任务需要全部工具。
- 不能保证结果正确。 外部数据可能过期，工具调用也可能失败。关键结论仍要回到权威来源和真实系统状态核验。
先理解两种连接方式
Codex 的 mcp add 当前支持两类连接：
| 类型 | 添加方式 | 适用情况 | 主要风险 |
|---|---|---|---|
| stdio | 在 -- 后写启动命令 | 本地 MCP 进程，通过标准输入输出通信 | 本地命令来源、文件访问、环境变量 |
| Streamable HTTP | 使用 --url | 远程 MCP 服务 | 网络传输、OAuth 权限、服务端数据处理 |
stdio 服务器本质上是你电脑上运行的进程。它的启动命令就是代码执行边界的一部分，所以只能运行你审查过的程序。HTTP 服务器由远端提供服务，但授权范围和数据处理仍由远端与当前客户端共同决定。
添加本地 stdio 服务器
示例命令：
codex mcp add docs -- /absolute/path/to/docs-mcp-server如果服务器需要非秘密的环境变量，可以按当前命令支持的方式传入：
codex mcp add docs --env DOCS_REGION=cn -- /absolute/path/to/docs-mcp-server示例中的 docs 是本地名称，可按用途起成容易识别的名字。路径必须是实际存在的可执行文件或明确的启动命令。不要从聊天消息中复制一条来历不明的长命令直接运行。
密钥不要写死在命令里
如果服务器必须使用 token，优先检查它是否支持从环境变量读取，并确保该变量来自当前受控会话。不要把真实密钥写在：
- 仓库的
.codex/config.toml； AGENTS.md；- shell 脚本的公开示例；
- MCP 命令参数；
- 文章截图或 issue 评论。
代码示例只使用占位符：
export DOCS_API_TOKEN="<由你的密钥管理系统提供>"随后按服务器文档启动。需要查看时也避免 printenv 输出完整秘密值。
添加远程 HTTP 服务器
示例：
codex mcp add company-docs --url https://mcp.example.com/mcp如果服务支持用环境变量传递 Bearer token，当前 mcp add 帮助提供 --bearer-token-env-var 参数：
codex mcp add company-docs --url https://mcp.example.com/mcp --bearer-token-env-var COMPANY_DOCS_TOKEN这里传入的是环境变量名称，不是 token 本身。具体是否适用、token 如何签发、服务支持哪些 header 和权限范围，都必须以该 MCP 服务文档为准。
对于 OAuth 服务，先添加配置，再登录：
codex mcp add company-docs --url https://mcp.example.com/mcp
codex mcp login company-docs在无图形界面的环境中，可使用当前帮助提供的无浏览器流程：
codex mcp login company-docs --no-browser它会打印授权地址并等待回调。只打开与已核对域名匹配的授权页面，不要通过聊天转发授权链接或验证码。
查看、检查和删除配置
列出已配置服务器：
codex mcp list查看某个服务器：
codex mcp get company-docs删除：
codex mcp remove company-docs退出某个 MCP 的 OAuth 登录：
codex mcp logout company-docs删除配置与撤销服务端授权不是同一件事。若组织要求彻底收回权限，还要在对应服务的账号安全页或管理员控制台撤销客户端访问，并检查本地是否残留 token。
配置文件长什么样
codex mcp add 会把配置写入 Codex 配置体系。通常位于用户级 $CODEX_HOME/config.toml 的 [mcp_servers.<name>] 表中；也可以通过 CLI 管理而不手写 TOML。不要假设所有客户端都读取同一个文件，具体以当前 Codex 版本和运行环境为准。
不要为了“团队共享”就把含凭据的服务器配置提交到仓库。团队级配置应通过组织允许的受管配置、密钥系统与权限管理分发。配置字段、沙箱与审批见 Codex 配置与安全指南。
权限审查：添加前问五个问题
- 来源是谁？ 核对发布者、域名、签名、版本和代码来源。
- 需要哪些数据？ 只授权当前任务真正需要的文档、仓库或数据集。
- 能执行哪些动作？ 只读查询与删除、发布、转账等写操作的风险完全不同。
- 凭据怎样保存和撤销？ 明确 token 有效期、存储位置、轮换与退出流程。
- 失败时会怎样？ 重试是否会造成重复写入？是否有人工确认与幂等设计？
一个 MCP 服务如果要求“全盘访问、读取所有环境变量、可任意执行命令”，应视为高风险配置，除非它在隔离环境中经过明确评审。
怎样验证 MCP 是否工作
先只调用只读工具，例如查询一篇测试文档：
请使用已配置的 docs MCP 查询 <测试文档名称>，只返回标题和更新时间。
不要调用写操作。然后检查：
- Codex 是否列出了预期工具；
- 请求是否发往正确服务；
- 返回内容是否与人工核对一致；
- 日志里是否出现不必要的敏感信息；
- 失败时是否给出可理解的错误，而不是无限重试。
不要用真实客户数据做第一次连通性测试。先准备公开或虚构样例，确认认证、权限、日志和撤销流程。
常见问题
codex mcp add 成功但工具没有出现
重新启动 Codex，检查 codex mcp list、服务器进程或 HTTP 地址，以及登录状态。运行 codex doctor 检查环境和配置。若是远程服务，确认协议版本、URL 和授权 scope 与文档一致。
浏览器登录完成，仍提示未授权
检查 OAuth 是否回调到当前本机、账号是否属于正确组织、权限是否授予，以及 token 是否被过期或撤销。必要时运行 codex mcp logout 后重新登录。不要通过关闭认证或放宽所有权限来绕过。
应该提交 MCP 配置到 Git 吗？
可以提交不含凭据、经过评审的配置模板，但不要把个人 token、私有服务器地址或生产凭据提交到仓库。团队配置应由组织明确支持的分发机制管理。
MCP 和 API 有什么区别？
MCP 是 AI 客户端发现并调用外部工具的一种协议；普通 HTTP API 是服务提供的接口。MCP 服务器可以封装 API，但会增加工具描述、授权和调用行为这一层，所以需要同时审查服务 API 和 MCP 服务器本身。