Codex CLI 中的 MCP 服务显示已连接，却看不到预期工具，说明问题已经越过“进程能不能启动”这一关，进入了工具发现、过滤和会话上下文阶段。服务在线并不代表它一定发布了工具，也不代表所有工具都会被 Codex加载。正确排查顺序是先确认服务器实际返回的工具清单，再检查 `enabled_tools`、`disabled_tools` 等过滤设置，最后处理会话缓存和权限边界。

一、先区分连接成功与工具可用

MCP 连接成功只说明客户端和服务端完成了基本通信。工具是否可见，还取决于服务端有没有声明 tools 能力、是否成功响应工具列表，以及客户端有没有过滤。某些 MCP 服务只提供 resources 或 prompts，本来就不会出现可调用工具。

先记录服务器名称、传输方式和状态，不要看到绿色连接标记就跳到权限配置。若同一服务在其他客户端也没有工具，问题更可能在服务端；若其他客户端能列出工具而 Codex不能，再检查 Codex配置和当前会话。

二、确认服务器实际发布了哪些工具

使用服务自带的调试方式或 MCP Inspector 查看工具列表。重点关注工具原始名称、数量和初始化时的标准错误。服务端升级后可能重命名工具，旧教程中的名称已经不存在；也可能因为缺少数据库、API 凭据或插件模块，只启动了基础服务而没有注册业务工具。

工具名通常区分大小写和字符形式。配置里写了近似名称不会自动模糊匹配。把服务端返回的名字与 Codex配置逐字对照，尤其检查连字符、下划线和命名空间。

三、检查 enabled_tools 是否只允许了部分工具

`enabled_tools` 适合给大型 MCP 服务做白名单，只加载确实需要的工具。但列表一旦存在，未列出的工具可能被过滤。若刚新增服务端工具，却没有同步更新白名单，就会出现“服务已连接、老工具可见、新工具消失”。

临时排查时可以备份配置，再移除过滤项或只保留一个已知存在的工具验证。不要在团队生产配置中长期开放所有高风险工具。确认原因后，应恢复最小范围，并写清每个允许项的用途。

四、检查 disabled_tools 是否覆盖了允许列表

禁用列表常用于屏蔽写操作、删除操作或成本较高的工具。配置层级较多时，上层允许了工具，下层却可能再次禁用。不要只看当前打开的 config.toml，要确认用户配置、项目配置、profile 和命令行覆盖后的最终值。

同一个服务器可能在不同配置层使用相同名称，却拥有不同过滤规则。先确定本次会话实际选用了哪个 profile，再检查对应层。为避免误判，可以把配置缩减成一个服务器、一个工具的最小样例，验证后逐步恢复。

五、服务器名称和工具名称不要混淆

MCP 配置中的服务器名称，是 Codex识别一组连接的标签；服务端返回的工具名，是组内具体能力。把服务器名写进工具白名单，或把完整展示名误当原始工具名，都可能导致过滤失败。

重命名服务器后，旧的权限记录、说明文档和调用习惯也可能失效。团队应固定命名规则，不要在不同电脑上分别叫 `docs`、`documentation` 和 `doc-server`，否则排查日志时很难对应。

如果大家想体验一线 AI 编程模型 codex 和 claude，用它们完成工具调用、代码修改和效率提升，可以参考以下教程文档进行接入配置，接入配置好后即可使用。文档教程：https://my.feishu.cn/wiki/NIgLwuuj1ibzJIkLGM0cgVNinzg

六、修改配置后重新建立会话

工具定义通常在会话启动时进入可用工具集合。你在另一个编辑器里修改 config.toml，不一定会让正在运行的会话重新加载全部 schema。保存配置后完全退出当前 Codex会话，再从正确项目目录启动，是最直接的刷新方式。

如果 MCP 服务自身也是长驻进程，还要确认旧进程是否被重新拉起。服务端代码已经更新、客户端却仍连接旧实例时，工具列表自然不会变化。检查进程启动时间和日志，比反复修改工具名更有效。

七、排除项目配置和 profile 覆盖

Codex 可以从用户层、项目层和指定 profile 读取配置。某个项目为了安全只开放只读工具，换到另一个目录却正常，这通常不是服务故障，而是项目配置生效。先确认信任状态和项目根目录，再查看实际配置来源。

命令行临时覆盖也要记录。测试时使用的 `-c` 或 profile 参数可能只在那一次启动中生效，下一次普通启动又恢复旧配置。把成功命令与失败命令并排比较，找出唯一差异。

八、工具可见但不能调用要转查权限

“列表里没有工具”和“工具出现但调用被拒绝”不是同一问题。后者通常与审批、沙箱、网络访问或工具自身认证有关。工具已出现在会话中，就不要继续围绕 enabled_tools 排查，而应保存拒绝信息，确认调用是否需要额外授权。

先选择无副作用的只读工具做测试。只读工具成功、写入工具失败，说明连接和发现正常，边界限制正在发挥作用。不要为了方便直接把整个 MCP 服务设成无限权限。

九、检查工具说明和发现提示

当工具很多时，Codex不一定会在每次任务中主动选择你期待的那个。工具虽然可用，但说明过于模糊，模型可能不知道何时使用。服务端应提供清楚、简短的工具描述，并明确输入参数和适用场景。

测试时可以直接要求列出当前相关工具，或明确说“使用某服务器的某个工具完成只读查询”。若明确点名能调用，自动任务却不选择，应优化服务说明和任务表达，而不是继续修改连接参数。

十、保留一份最小可复现配置

最终应得到一个不含真实密钥的最小配置：单一服务器、确定的启动命令、一个已知工具、明确过滤项和一条只读测试指令。记录 Codex版本、服务器版本、启动目录和重启步骤。以后再出现工具消失，可以快速判断是服务端列表变化、配置过滤、会话未刷新还是权限拒绝。

稳定验收要同时满足四点：服务已连接、工具列表含目标项、当前会话能发现它、一次低风险调用成功。只看连接状态会漏掉后面三层，也正是“已连接但工具不显示”最容易让人绕圈的原因。