MCP 连接、发现与调用排障

先确定失败在哪一层：没有启动、连接失败、未发现工具、工具被过滤，还是调用本身失败。单纯增加 timeout 不会解决全部问题。

状态含义

状态	意义
CONNECTING	正在建立连接
CONNECTED	已连接
DISCONNECTED	未连接或发生错误
Discovery COMPLETED	发现流程结束，可能包含错误

COMPLETED 不等于所有服务成功。启动后台连接错误默认安静，只给出检查提示；运行 /mcp list、/mcp auth、调用相应工具或 prompt 后会重新显示详细诊断。

无法连接

核对 command/args/cwd、程序是否安装与可执行、远程 URL 和 transport 是否一致。Stdio 还需当前目录可信；服务命令在普通终端可运行，也不保证在沙箱中同样具备依赖与路径。

工具未出现

检查服务是否真的实现工具列表、includeTools/excludeTools 是否全部过滤，以及是否有 schema 错误。当前工具都使用 mcp_ 前缀 FQN；不要根据旧截图中的裸工具名排查。

官方说明会为 API 兼容移除 $schema、additionalProperties，以及特定 anyOf 中的 default，并递归处理。服务 schema 的每一项约束不一定原样保留到模型端，服务端仍应验证实际输入。

工具执行失败

检查传入字段、服务端业务错误、认证 scope 和超时。服务 Connected 仅表示连接已建立，不能证明凭据有某项业务操作权限。

沙箱差异

确认可执行文件在沙箱内可见，镜像含依赖，挂载路径和网络允许，必要变量正确传入。MCP 的 env 默认脱敏描述与当前设置存在差异，见环境配置，不要靠假设调整凭据。

调试入口

gemini --debug 增加诊断；交互 F12 打开调试控制台。服务 stderr 会被捕获，先检查具体错误，再独立测试最小服务。修改能力后用 /mcp reload 重扫。

重名与覆盖

同一服务别名和同名工具可发生覆盖；给不同服务使用明确名称，避免下划线导致策略身份解析歧义。扩展与本地同名配置还有特定合并规则，应检查最终可见工具，而不只是某一个配置文件。