# MCP 连接、发现与调用排障

> 逐层检查服务状态、过滤、schema、认证和沙箱环境。

- 网址：https://funcoding.ai/agents/gemini-cli/build/mcp-troubleshooting/
- 核实日期：2026-10-08（命令、配置和价格以官方文档为准）
- 官方来源：[Gemini CLI 官方文档：MCP servers](https://geminicli.com/docs/tools/mcp-server)、[Gemini CLI 官方文档：MCP setup tutorial](https://geminicli.com/docs/cli/tutorials/mcp-setup)

---
先确定失败在哪一层：没有启动、连接失败、未发现工具、工具被过滤，还是调用本身失败。单纯增加 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 默认脱敏描述与当前设置存在差异，见[环境配置](https://funcoding.ai/agents/gemini-cli/build/mcp-configuration/)，不要靠假设调整凭据。

## 调试入口

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

## 重名与覆盖

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