浏览 AI 知识库
MCP 工具列表为空，或工具可见但调用失败怎么查
工具列表为空和工具调用失败发生在不同阶段。前者先查发现与注册，后者再看参数、权限和服务响应，不要把两者都归结为 Server 没启动。
“没有工具”和“工具能看见但不能用”，排查入口完全不同
客户端显示已连接，却没有任何工具；另一次工具可见，调用后报参数错误。把这两种现象当成同一故障会一直重启。
- 连接、发现和调用状态分开
- 参数按实际 schema 验证
- 修复用原失败输入复测
MCP 工具列表为空，先从“工具列表为空”这一类现象查起
工具列表为空
- 原因
- Server 未声明工具、启动后立即退出、客户端未刷新或该连接只提供资源。
- 怎么改
- 查看 Server 能力和日志，重载客户端，确认配置的确指向预期 Server。
工具可见但参数报错
- 原因
- 客户端传入字段与当前 schema 不一致，必填、类型或枚举变化。
- 怎么改
- 查看工具当前 schema，用最小参数调用，不从旧示例推断。
工具开始调用后失败
- 原因
- 工具内部依赖、网络、凭证或目标资源权限错误。
- 怎么改
- 关联调用 ID、Server stderr/日志和上游状态，定位第一处失败。
某客户端能用，另一客户端不能
- 原因
- 客户端支持、配置作用域、传输或授权行为不同。
- 怎么改
- 分别按当前客户端文档核对，不直接复制配置并假设兼容。
复测前，固定原始现象、环境和目标
| 需要确认 | 本例内容 |
|---|---|
| 现有材料 | 场景 A 握手成功、tools/list 为空；场景 B 列表含 `read_file`，调用返回 schema validation error。 |
| 不能越过的边界 | 区分连接、工具发现、schema 与执行；保存客户端请求和 Server 日志；只用教学参数。 |
| 要交付的结果 | 工具发现与调用对照表 |
工具列表、schema 和最小调用要分开留证
| 阶段 | 实际结果 | 证据 | 判断 |
|---|---|---|---|
| 连接 | Server 进程持续运行 | 启动时间、PID、stderr | 只证明进程未退出 |
| 发现 | Client 显示 `list_directory` | 工具名和当前 schema | 证明能力已声明 |
| 参数 | 空路径返回必填字段错误 | 原始错误和 schema | 按 schema 补最小路径 |
| 调用 | 测试目录返回 3 个文件名 | 调用 ID、结果和 Server 日志 | 只读链路可用 |
工具名是演示。真实诊断应保存当前 Server 版本、客户端版本和脱敏后的实际 schema。
MCP 工具列表为空：按原条件复测的结果
原始现象
“MCP 不能用”没有说明工具是否出现、调用是否发出和 Server 是否收到。
工具发现与调用对照表
A 定位 Server 未注册工具；B 定位参数名从 `path` 改为 `file_path`。修复后 tools/list 非空，同一只读文件调用成功；两条问题分别记录。