太长不看版
- Codex 从 ~/.codex/config.toml（全局）或 .codex/config.toml（项目级）读取 MCP server，每条配置是一个 [mcp_servers.<名称>] 表：本地 stdio server 写 command/args，远程 server 写 url。
- codex mcp add context7 -- npx -y @upstash/context7-mcp 一条命令装好 stdio server，不用手动改文件；远程 server 用 codex mcp add <名称> --url https://mcp.example.com/mcp 注册。
- 远程 server 首次连接时会在浏览器里完成授权（Codex 会提示 Detected OAuth support 并打开同意页），之后随时可以用 codex mcp login <名称> 重新登录。
- 验证用 TUI 里的 /mcp 或终端里的 codex mcp list。0.160.1 起还会在启动带远程环境变量的 remote stdio server 时保留 SYSTEMROOT、TEMP 和 TMP。
OpenAI Codex + MCP: How to Install MCP Servers in Codex (Step by Step)
频道：Nathan Sebhastian8:48
OpenAI Codex Tutorial #9 - MCP Servers
频道：Net Ninja6:46
How to Add MCP Servers to OpenAI Codex CLI
频道：Snyk9:14
Connect Codex to an MCP server — official documentation
官方文档：developers.openai.com/codex
本页的每条命令、文件路径和配置键都对照 Codex 官方 MCP 文档核实过；上面的视频是画面与事实来源，OAuth 同意页和桌面端 MCP 菜单都出自实测演示。
截图版权归各自创作者所有，并深链到对应时间点；未使用任何人脸镜头。
Codex 接入 MCP server 分步走查
第一部分 —— 装上第一个 stdio server
- 1
在官方 MCP 文档里挑一个 server
打开 developers.openai.com/codex/mcp——Codex 官方文档始终保留最新的命令语法，CLI 和 IDE 扩展共用这套配置。文档里列了几个值得一试的现成 server：查框架最新文档的 Context7，还有 Figma、GitHub 等等。MCP server 成百上千，第一次测试建议挑 Context7 这类只读的。
官方 Connect Codex to an MCP server 页面，codex mcp add 语法和 Context7 示例命令都在眼前。跳到 0:20 观看 - 2
用 codex mcp add 一键安装
复制示例到终端执行：codex mcp add context7 -- npx -y @upstash/context7-mcp。双横线后面的部分是启动 server 进程的命令。Codex 回一句 "Added global MCP server 'context7'"——global 意思是写进了用户级配置，所有项目都能用。
一条命令、不改文件：CLI 确认 server 已加入全局配置。跳到 0:45 观看 - 3
看看 CLI 往 config.toml 里写了什么
codex mcp add 本质上是 ~/.codex/config.toml 的生成器。打开文件就能看到 [mcp_servers.context7]，下面是 command = "npx" 和 args = ["-y", "@upstash/context7-mcp"]。这些条目也完全可以手写：加一张 env 表放 API key，给启动慢的 server 设 startup_timeout_sec（默认 10 秒）和 tool_timeout_sec（默认 60 秒）。来源卡里 Snyk 和 Net Ninja 的视频走的就是手改文件这条路。
- 4
启动 Codex，用 /mcp 验证
在项目里启动 codex，输入 /mcp。MCP Tools 面板会列出每个已配置 server 的状态、确切启动命令和它提供的工具——Context7 显示 query_docs 和 resolve-library-id 两个工具。这里少了谁，说明条目写错了文件或没能启动。
Codex TUI 里的 /mcp 面板：context7 已启用，两个工具列得清清楚楚。跳到 1:05 观看
第二部分 —— 先用起来，再上远程
- 5
发起一个真正会用上 server 的提示
MCP 工具按需调用，所以提问要带上它："用 Context7 查一下最新的 Tailwind CSS 配置文档"。Codex 会先解析库名，再通过 MCP server 拉文档，并在回答里附上来源链接。看着工具调用在屏幕上滚过，就是 server 全链路可用的最直接证明。
Codex 的回答里引用了它通过 MCP server 拉到的 Context7 文档链接。跳到 1:30 观看 - 6
用 --url 接入远程 server
很多服务商直接托管 MCP server——本地不用跑进程，也不需要 npx。用 codex mcp add context7 --url https://mcp.context7.com/mcp 注册。Codex 会自动识别 OAuth 支持，打印 "Detected OAuth support. Starting OAuth flow..." 并打开浏览器。落到 config.toml 里就是 [mcp_servers.context7] 下的一行 url = "https://mcp.context7.com/mcp"。
一个终端看完整条远程链路：--url 添加、识别 OAuth、授权 URL，直到 Successfully logged in。跳到 2:22 观看 - 7
在浏览器里点掉 OAuth 同意页
浏览器会问你是否允许 Codex 以你的身份访问服务商账号。核对请求的权限范围，点 Allow，终端随即确认 "Successfully logged in"。如果 server 不提供 OAuth 流程，就用 codex mcp login <名称> 单独登录；基于令牌的 server 则用 bearer_token_env_var 指向一个环境变量。
Context7 的授权页：核对 Codex 要的权限，然后 Allow。跳到 2:02 观看 - 8
用项目级 .codex/config.toml 圈定作用域
只在某个仓库有意义的 server——比如直连数据库的 stdio server DBHub——适合放进项目配置。在仓库里建 .codex 目录，写一个 config.toml 放 [mcp_servers.dbhub] 条目，用 --dsn 参数传连接串（把文档里的 Postgres 示例改成你实际用的 MySQL 之类）。提交进仓库，同事就能用同一套 server；项目需要在受信任列表里才会加载。
项目级 .codex/config.toml：DBHub 以 stdio 运行，args 里带着数据库 DSN。跳到 3:30 观看
第三部分 —— 真实 server 与日常管理
- 9
通过 MCP 工具查询数据库
配好 DBHub 后直接问 Codex："找到 Petco 数据库，解释一下这些表"，再来一句"卖得最好的商品是什么？"。Codex 会调用 server 的 describe_table 和 execute_sql 工具，执行 SQL 前先请求许可，然后用你库里的真实数据回答。做后端时，这是排查表结构和校验数据最快的一条路。
Codex 调用 dbhub 的 execute_sql 工具，答出了畅销商品和它的销售额。跳到 4:40 观看 - 10
用远程 server 接入 GitHub
github/github-mcp-server 的 README 里有 Codex 的接入说明：加一个 [mcp_servers.github] 条目，url = "https://api.githubcopilot.com/mcp/"，然后走 OAuth 或把个人访问令牌导出成环境变量（在 GitHub Settings 的 Developer settings 里建 fine-grained PAT，勾上 Administration 和 Contents）。这类远程 server 和第 6 步的 Figma MCP server 是同一个套路。
GitHub MCP server 的安装指南：Codex CLI 条目加上 OAuth/PAT 认证说明。跳到 5:22 观看 - 11
重启 Codex，把工具用起来
重启 codex，注意启动横幅："Starting servers (0/3): context7, dbhub, github"。现在一句"帮我把 openai/codex 仓库 fork 到我的账号"就够了——Codex 自己挑 GitHub 的 fork 工具、请求批准、完成操作。不需要任何逐任务设置：从现在起这些工具就是每个会话的一部分。
- 12
用 codex mcp list 和桌面端管理 server
终端里 codex mcp list 列出所有已配置 server；想删掉某个，就把它的配置块从 config.toml 里删掉，再跑一遍命令确认。桌面端和 IDE 扩展读的是同一份 ~/.codex/config.toml，所以这里装的 server 会出现在桌面端 Settings 的 MCP servers 页面，带开关可切换。
Codex 桌面端的 MCP servers 设置页：context7、dbhub、github 各带开关，下面还有推荐 server。跳到 7:30 观看
本地 stdio 与远程 MCP server 怎么选
两类 server 写在同样的 [mcp_servers.*] 表里、出现在同一个 /mcp 面板中——区别只在于 server 跑在哪里、怎么认证。按 server 逐个选，不必全站一刀切。
- 1本地 stdio：Codex 用 command 加 args 自己拉起一个进程，通常是 npx 或某个可执行文件。它跑在你机器上，能直接够到 localhost 服务（走查里 DBHub 查本地 MySQL 靠的就是这个），代价是运行时和升级都归你管。
- 2远程：Codex 通过 streamable HTTP 访问一个托管 url。没有进程要养，认证集中管理——默认 OAuth，令牌型用 bearer_token_env_var 和 http_headers。官方文档自己的示例就是 [mcp_servers.figma] 配 url = "https://mcp.figma.com/mcp"。
- 3远程执行的 stdio：一条实验性的中间路线。给 stdio 条目加 experimental_environment = "remote"，它的执行就挪到远程执行器上，哪些环境变量跟着走由 env_vars 决定——包括标记为 source = "remote" 的条目。0.160.1 加固的正是这条路。
- 4作用域：codex mcp add 永远写全局的 ~/.codex/config.toml；项目专属 server 放仓库里的 .codex/config.toml（仅限受信任项目）。到处要用的工具放全局，带环境凭证的一律进项目级。
- 5两者通用的控制项：启动慢就调 startup_timeout_sec（默认 10 秒）和 tool_timeout_sec（默认 60 秒）；用 enabled/disabled_tools 圈定 Codex 能调哪些工具；依赖某个 server 时设 required = true，起不来就干脆不让 Codex 启动。
一个务实的默认：Context7 这类只读文档 server 可以放全局；凡是碰凭证或数据的——DBHub、带 PAT 的 GitHub——都进项目级配置，随仓库一起评审、一起吊销。
配置好了却不工作：最常见的几种原因
Codex 里 MCP 的故障绝大多数是作用域、超时或认证问题——按这个顺序排查，先别怀疑 server 本身。
- 1/mcp 里看不到 server：先查改的是哪个文件。全局条目在 ~/.codex/config.toml；项目条目在 .codex/config.toml，且目录必须受信任。终端里跑 codex mcp list 能看到 Codex 真正认到的列表。
- 2启动超时：startup_timeout_sec 默认只有 10 秒，冷启动 npx 拉一个大包很容易超。预装那个包，或者调大条目里的 startup_timeout_sec。
- 3工具调用报 401/403：凭证缺失或过期。OAuth server 跑 codex mcp login <名称>，令牌型设好 bearer_token_env_var 并 export 变量。修完之后 /mcp 里应该恢复 enabled。
- 4远程 stdio server 报出诡异的 Windows 相关错误：0.160.1 之前，带显式远程环境变量启动 remote stdio MCP server 时可能丢掉 SYSTEMROOT、TEMP 和 TMP，破坏 Windows 执行器的启动环境。升级到 0.160.1 或更高版本即可。
- 5server 启动正常但回答错误或为空：不少托管 server 走了 OAuth 仍要自己的 API key——比如 Context7 就要通过 env 传 API key。查服务商文档拿到确切的环境变量名，加进条目的 env 表。
调试期两个顺手的开关：依赖的 server 设 required = true，挂了就不会静默启动；暂时不用的设 enabled = false，配置留着、随时恢复。