浏览 AI 知识库
Codex MCP配置教程：安装、授权和第一次只读调用
Codex 里配置 MCP，要分别确认 Server 能启动、配置写在当前作用域、权限已授权、工具已发现。第一次调用先选只读动作，便于定位问题。
沿完整工作流推进
前一阶段的可检查结果，是下一阶段的输入；中间证据不足时停在当前阶段。
终端里 Server 能运行，为什么 Codex 里还是看不到工具
Server 在终端能启动，Codex 里却看不到工具。用户反复重装，实际问题是配置写在另一个作用域，当前客户端没有加载。
- 配置作用域与加载状态明确
- 工具列表截图或日志已保存
- 只读结果能回到真实文件
先确认这次任务的起点、边界和交付
| 需要确认 | 本例内容 |
|---|---|
| 现有材料 | Windows、Codex 当前版本、本地 stdio Server；配置包含命令与只读目录，不含秘密；有 Server stderr 日志。 |
| 不能越过的边界 | 配置路径、作用域和语法以当前 Codex 官方文档为准；先确认工具发现，再做一次只读调用；不开放整个磁盘。 |
| 要交付的结果 | 配置记录、工具列表和只读结果 |
从“确认传输和作用域”走到“运行只读测试”
| 当前阶段 | 实际处理 |
|---|---|
| 确认传输和作用域 | 记录 Codex 版本、系统、Shell 和配置位置；本地命令选择 stdio，远程 MCP URL 选择 streamable HTTP。 |
| 用 CLI 添加或手动写配置 | stdio 使用 `codex mcp add NAME -- COMMAND`，远程端点使用 `codex mcp add NAME --url URL`。手动编辑时先备份 `config.toml`，只增加对应 `[mcp_servers.NAME]` 区块。 |
| 分离凭证并处理远程登录 | stdio 可用 `--env KEY=VALUE` 注入运行环境；streamable HTTP 可用 `--bearer-token-env-var ENV_VAR` 引用环境变量。需要 OAuth 时按 Server 说明运行 `codex mcp login NAME`；完整 Token 不进入仓库、截图或公开 TOML。 |
| 用 JSON 验证登记 | 运行 `codex mcp list --json` 查看列表，再运行 `codex mcp get NAME --json` 核对目标 Server 的传输、命令或 URL；为空时先查配置读取位置和 Server 日志。 |
| 运行只读测试 | 读取一个测试资源，保存参数、结果和日志；发送、创建、修改、删除或部署留到人工确认。 |
先用 JSON 回读配置，再做一次无副作用调用
| 检查层 | 输入/命令 | 预期 | 失败时先查 |
|---|---|---|---|
| 登记 | `codex mcp add files -- /path/server` | 只新增 files，不改其他 Server | 当前 scope、命令路径和配置文件 |
| 列表 | `codex mcp list --json` | 名称、状态和传输可见 | JSON 是否来自当前用户配置 |
| 详情 | `codex mcp get files --json` | stdio 命令与路径准确 | TOML 拼写、环境变量和版本 |
| 只读调用 | 列出测试目录或读一份无敏感文件 | 结果含预期文件名，未发生写入 | Server stderr、权限和白名单 |
命令示例按当前 Codex 版本核对；不要把完整 Token 写入 shell 历史、截图或仓库。
完成后的配置记录、工具列表和只读结果
记录客户端版本和实际配置来源，重启/刷新后工具列表出现 `list_files` 与 `read_file`。首次调用只读取 `D:/demo/docs/readme.txt`，返回内容与文件一致，写工具未授权。
为什么“工具列表出现，调用仍失败”还不能交付
工具列表出现，调用仍失败
- 原因
- 发现阶段和执行阶段使用了不同工作目录、变量或权限
- 怎么改
- 比较 Client 调用参数与 Server 日志，逐项核对 cwd、环境和白名单