Codex 里添加了服务，为什么工具还是不可用？

常见原因是 OAuth 没完成、环境变量没传进服务、服务类型选错，或者只是服务被登记了但尚未成功建立连接。

什么时候用全局配置，什么时候用项目级配置？

长期通用的服务适合全局配置，只服务于某个仓库或团队项目的服务更适合项目级 `.codex/config.toml`。

接入后第一步应该测试什么？

优先测试列出工具或读取只读资源，不要一开始就执行写操作，这样更容易确认连接和认证是否正常。

Codex接入MCP服务：配置文件写法、验证步骤与排错

如果你想让 Codex 不只会读代码，还能连接文档、设计、后台或内部 API，最直接的办法就是给它接入 MCP 服务。好消息是，Codex 官方已经把主要接入方式写得比较清楚：你可以在桌面端图形界面里添加，也可以通过命令行或 `config.toml` 做更细粒度的配置。真正容易出错的地方往往不是“有没有入口”，而是服务器类型、配置作用域、环境变量传递和接入后的验证步骤。

先确认 Codex 支持什么类型的 MCP 服务

官方文档说明，Codex 支持两大类服务：一类是 STDIO，本质上是本地进程，通过命令启动；另一类是 Streamable HTTP，也就是通过地址访问的远程服务。前者常用于本地脚本、本地文件系统或开发工具链；后者常用于远程平台、团队共享服务或带 OAuth 的在线能力。理解这一步很重要，因为你后面写的字段完全不同：STDIO 需要命令和参数，HTTP 则需要 URL、认证信息以及可能的 OAuth 流程。

最简单的两种接入方式

第一种是直接用图形界面：在桌面端设置里进入 MCP servers，添加服务名称，选择 STDIO 或 Streamable HTTP，再填写命令或 URL，保存后重启。第二种是用命令行：官方给出了 `codex mcp add` 和 `codex mcp list` 这类命令，适合已经熟悉终端的用户。命令行方式的优点是可复制、可记录，尤其适合你后面要反复迁移或给同事复现。

什么时候应该改 config.toml

当你希望把配置写得更明确、可审查、可按项目隔离时，最好改 `~/.codex/config.toml` 或项目级 `.codex/config.toml`。官方文档明确提到，Codex 使用 `[mcp_servers.]` 这样的表结构定义每个服务。项目级配置特别适合“这个仓库只需要这几个服务”的场景，可以避免把所有服务器都堆到全局环境里，也能减少误连错连的概率。

STDIO 配置时要看这几个字段

官方列出的关键字段包括 `command`、`args`、`env`、`env_vars` 和 `cwd`。最常见的误区有三个：第一，把服务器自身参数写到 Codex 参数位置，忘了区分谁属于命令、谁属于服务；第二，遗漏环境变量，导致服务能启动但认证失败；第三，在错误目录启动，结果本地服务找不到依赖或配置文件。只要是本地服务，`cwd` 和环境变量都值得认真核对。

HTTP 配置时重点看认证和验证

对于远程服务，Codex 文档强调支持 Bearer Token、OAuth 以及某些第一方可信服务的会话认证。你的检查重点应该放在三件事上：服务 URL 是否正确、认证方式是否和官方文档一致、是否需要在添加后再完成一次登录。很多人看到“已添加成功”就以为可以用了，但实际上 OAuth 服务如果没有完成授权，工具往往不会完整显示。

一个可直接对照官方字段的配置示例

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

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }

这段示例遵循当前 OpenAI 官方文档的真实字段：本地 stdio 直接写 `command` 和 `args`，远程 Streamable HTTP 直接写 `url`，需要 Bearer Token 时再补 `bearer_token_env_var`，而不是额外发明一个没有官方依据的 `transport` 字段。你可以把它当成“字段结构模板”直接对照自己的服务文档替换值；如果服务还要求固定头、环境头或 OAuth scopes，再继续补 `http_headers`、`env_http_headers` 或 `scopes` 即可。

接入失败时优先排查什么

服务类型选错：把 HTTP 服务按 STDIO 配，或者反过来。
命令能启动但缺依赖：本地环境没有对应包、可执行文件或解释器。
环境变量没传进去：服务启动了，却拿不到令牌。
项目级配置未被当前工作区信任或未生效。
OAuth 没做完：服务已存在，但工具列表为空或状态异常。

总结

Codex 接入 MCP 的关键不是把服务“加进去”，而是把配置作用域、服务类型、认证方式和验证顺序都做对。你只要记住官方推荐的三个抓手——`codex mcp add`、`codex mcp list`、`config.toml`——再坚持先只读验证、后逐步放权，整个接入过程就会稳很多。

Codex接入MCP服务：配置文件与验证步骤