Codex 配好 MCP 但工具不出现怎么办？

Codex MCP 工具配置后不显示时，按配置文件位置、运行环境、服务启动、权限范围、日志和最小工具集排查。

• 站内相关：Codex 接了很多 MCP 工具后怎么避免用错权限
• 站内相关：Codex 命令行总读到旧 API 地址怎么办
• 站内相关：Codex 命令找不到或路径不对怎么办
• 站内相关：CCSwitch 配置改了却没生效怎么办

适用场景：配置写了，Codex 里就是看不到工具

这篇适合给 Codex 接本地工具、文档检索、数据库只读查询、浏览器测试或内部系统 MCP 服务的开发者。常见表现包括：配置文件明明新增了 server，重启后工具列表没有变化；桌面端能看到，命令行看不到；远程任务能调用，本地 IDE 不行；或者工具出现了，但一调用就权限拒绝。MCP 配置不生效时，很多人第一反应是反复改 JSON，实际更应该先确认 Codex 当前运行的是哪一个配置目录、哪一个用户和哪一个工作区。

永沃云枢在 https://ai.jn83.com 的 Codex 接入文章里经常强调，AI API 接入和模型调用管理要先分清“配置已保存、服务已启动、客户端已加载、权限已授权”四个状态。它们不是一回事。只要其中一个环节没对上，工具就可能不可见。

操作步骤：从路径到权限逐层排查

第一步，确认配置文件路径。不要凭记忆判断，直接让 Codex 或终端输出当前用户目录、工作区目录和配置加载路径。桌面应用、CLI、远程工作区可能读取不同位置的配置。Windows、macOS、Linux 的路径也不同，复制教程时尤其容易放错目录。

第二步，检查 JSON 或 TOML 结构。工具名不要重复，命令路径要使用可执行文件的真实路径，参数里涉及空格要拆成数组，不要把一整串 shell 命令塞进单个字段。需要环境变量时，先确认当前进程能读到变量，而不是只在另一个终端窗口里设置过。

第三步，单独启动 MCP 服务。先不通过 Codex 调用，直接在终端里运行服务命令，看是否能启动、是否立即退出、是否输出鉴权错误。若服务依赖 Node、Python 或浏览器驱动，版本和 PATH 必须和 Codex 进程一致。

第四步，重启正确的客户端。只关闭聊天窗口通常不够，可能需要重启 Codex 桌面端、IDE 插件或远程任务会话。重启后先看工具清单，再做一次只读调用，例如列出资源、读取测试文档或查询固定样本。

常见问题/避坑：工具出现不代表能安全使用

第一个坑是权限过大。为了让工具赶紧出现，把文件系统、数据库、浏览器和远程命令都开放给同一个 server，后面很难审计。建议先只接一个只读工具，确认加载链路正常，再逐步扩展。第二个坑是本地和远程混用。远程 Codex 看到的文件系统不是你的本机桌面，配置里写本机绝对路径，远程环境当然找不到。

第三个坑是把 CCSwitch 配置、AI API Key 和 MCP 服务放在同一份可写目录里。Codex 排错时如果误改配置，可能同时影响模型路由和工具权限。更稳妥的做法是把密钥文件只读挂载，把日志目录和临时目录分开。第四个坑是没有记录工具版本。工具升级后参数名变化，老配置仍能启动但调用失败，日志里只显示通用错误。

检查清单：确认四个状态都成立

配置路径正确；配置语法正确；命令可单独启动；Codex 客户端已完整重启；工具清单里能看到名称；只读测试调用成功；失败日志能定位到服务端还是客户端；权限范围符合任务需要；没有把生产 Key、数据库写权限和危险命令默认暴露给模型。

如果排查超过半小时还没有结果，建议把配置缩到最小：只保留一个 server、一个工具、一个固定输入。最小样例跑通后，再逐项加回环境变量、鉴权、网络代理和工作区路径。

FAQ：能不能把所有 MCP 工具一次性接上？

技术上可以，维护上不建议。工具越多，模型选择成本和误操作风险越高。先按任务类型分组，例如文档检索、浏览器验收、只读数据库、文件分析。每组写清用途、权限、负责人和停用方法。这样 Codex 调用工具时更容易解释原因，人工复核也更有依据。

如果是团队共享配置，建议把“最后一次确认能用的版本”写进 README，包括客户端版本、服务命令、依赖版本和一次成功调用样例。下次有人说工具不见了，可以先对照这份基线，而不是每个人都重新猜一遍。