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版本、服务器版本、启动目录和重启步骤。以后再出现工具消失可以快速判断是服务端列表变化、配置过滤、会话未刷新还是权限拒绝。稳定验收要同时满足四点服务已连接、工具列表含目标项、当前会话能发现它、一次低风险调用成功。只看连接状态会漏掉后面三层也正是“已连接但工具不显示”最容易让人绕圈的原因。