给 Codex 添加远程 MCP：先确认配置格式，再验证工具可用

这次折腾的是给 Codex 接一个远程 MCP 服务，然后再安装对应的 skill。事情本身不复杂：拿到服务地址和认证信息，写进 Codex 配置，再让 Codex 重新加载。

但这里容易出错的地方也很明显。很多服务给的是一段通用 MCP JSON，Codex 本地配置用的却是 TOML；有些服务用 Authorization: Bearer ...，有些用 x-api-key；还有些客户端支持环境变量插值，有些更适合用专门的 env_http_headers。如果直接照抄，表面看起来像是“已经配置了”，实际启动时可能根本没被识别。

我更推荐把这类事情拆成四步：先看当前配置格式，再写最小配置，然后用 Codex 自己的命令读回，最后再安装配套 skill。

一、先看 Codex 现在怎么写 MCP

不要一上来就把对方给的 JSON 粘进配置文件。先看本机已有的 MCP 配置长什么样，再看 Codex 当前版本支持哪些字段。

最直接的方式是查帮助：

codex mcp --help
codex mcp add --help
codex mcp list

如果是远程 HTTP MCP，通常会看到 --url、--bearer-token-env-var 这类选项。它说明 Codex 知道这种服务器不是本地命令，而是一个 HTTP endpoint。

这里要注意一点：服务文档里写的 mcpServers JSON 不一定能原样放进 Codex 的 config.toml。JSON 里的：

{
  "url": "https://example.com/mcp",
  "headers": {
    "Authorization": "Bearer ..."
  }
}

到了 Codex TOML 里，通常要改成类似这样：

[mcp_servers.example]
url = "https://example.com/mcp"
env_http_headers = { "x-api-key" = "XQUIK_API_KEY" }

如果服务使用标准 Bearer token，也可以优先考虑：

[mcp_servers.example]
url = "https://example.com/mcp"
bearer_token_env_var = "EXAMPLE_API_TOKEN"

这样 token 放在环境变量里，不会直接写死在配置文件中。需要自定义 header 时，再用 http_headers 或 env_http_headers。

二、认证信息尽量不要硬写

本地配置文件不是公开仓库，但也不代表可以随便放密钥。尤其是这类 MCP token，通常能代表你的账号去调用第三方服务。一旦把它贴进聊天记录、日志或者代码仓库，后面就很难确认有没有泄露。

更稳的做法是把真实 token 放进环境变量：

export XQUIK_API_KEY="你的真实 key"

然后在 MCP 配置里只引用变量名：

[mcp_servers.xquik]
url = "https://xquik.com/mcp"
env_http_headers = { "x-api-key" = "XQUIK_API_KEY" }

这样配置文件里只有变量名，没有密钥本身。以后要换 key，也只需要换环境变量或 secret store，不用到处找配置。

当然，有些服务文档会给 Authorization: Bearer ... 的写法。遇到这种情况也不要急着复制完整值。先确认 Codex 支不支持 bearer_token_env_var。能用环境变量，就让 Codex 自己从环境变量读。

三、写完以后用 Codex 自己读回

很多配置问题不是靠肉眼看出来的，而是靠客户端读回发现的。写完以后，至少跑一下：

codex mcp get xquik
codex mcp list

正常情况下，你应该能看到这个 MCP 是启用状态，transport 是远程 HTTP 类型，URL 正确，认证字段也被识别了。认证值一般会被打码，这是好事。

如果这里显示不出来，先别急着怀疑服务端。更常见的问题是：

• 配置段名写错了，比如 mcpServers 和 mcp_servers 混用。
• JSON 写法没有转换成 TOML。
• header 字段名不被当前客户端识别。
• 把 token 直接放进了不支持的字段。
• 当前 Codex 线程还没重新加载配置。

这个阶段只要能被 codex mcp get 正确读出，就说明本地配置至少过了第一关。

四、再安装对应的 skill

MCP 解决的是“工具怎么连上”，skill 解决的是“什么时候该用、怎么安全地用”。比如 X/Twitter 这类数据工具，光有 API 还不够，还要知道哪些是读取、哪些是写入、哪些会消耗额度、哪些动作必须先让用户确认。

安装 GitHub 上的 skill 时，不建议把整个仓库直接塞进 skills 目录。先看仓库结构，确认真正的 skill 路径。很多仓库会把 skill 放在：

skills/<skill-name>

安装时应该装这个子目录，而不是仓库根目录。装完以后检查三件事：

ls ~/.codex/skills/<skill-name>
test -f ~/.codex/skills/<skill-name>/SKILL.md

如果有 metadata.json 或 references/，也顺手看一下是否完整。一个比较完整的 skill 往往不只有一份 SKILL.md，还会有 API 参考、工作流说明和安全规则。

五、最后做一次复查

完成以后，不要只停在“文件已经写了”。至少确认这几件事：

• codex mcp list 能看到新 MCP。
• codex mcp get <name> 能正确显示 URL 和认证方式。
• skill 目录里有 SKILL.md。
• 如果新装了 skill，重启 Codex 后再试。
• 公开记录里没有留下真实 token、邮箱、个人路径或完整配置。

这类配置的重点不是“把一段配置放进去”，而是确认 Codex 真的读懂了它。MCP 和 skill 都属于会影响工具调用行为的东西，写完以后多跑两个读回命令，比事后排查省心很多。

我的经验是：远程 MCP 先用最小配置接通，再补安全和使用规则；skill 则先确认路径和结构，再让 Codex 重启加载。这样做慢不了几分钟，但能避开很多看起来很小、实际很烦的配置问题。