For the complete documentation index, see llms.txt. This page is also available as Markdown.

MCP 排错

MCP 问题通常出在四个环节:服务器没有启动、运行环境不完整、认证或地址错误、Agent 没有绑定。按顺序排查,比反复重装更快。

从服务器启动、运行环境、认证网络到 Agent 绑定和调用链的 MCP 排错流程图
按顺序检查,先确认服务器本身能运行,最后再看 Agent 调用链。

快速判断

现象
先检查
常见原因

服务器无法启动

【设置】→【MCP】→服务器详情→日志

命令不存在、参数错误、环境变量缺失

远程连接失败

URL、网络代理、认证

地址协议错误、服务不可达、令牌失效

服务器正常但没有工具

服务器详情中的工具列表

服务未返回工具或权限不足

工具存在但 Agent 不会调用

Agent【MCP】

未绑定、工具关闭、配置未从下一条消息生效

调用停在等待

Agent 权限请求和右侧【状态】

需要人工批准或后台任务未完成

调用返回异常

调用链的输入、输出和状态

参数不符合工具定义、服务端错误

排查顺序

1

1. 在 MCP 设置页单独验证服务器

确认状态正常,能看到工具、资源或提示词。这里都没有内容时,不要先调整 Agent。

2

2. 检查运行环境

本地命令需要对应运行时和可执行文件。路径或命令中包含空格时,按服务器说明拆分命令与参数,不要把整段配置当成一个路径。

3

3. 检查认证与网络

确认 URL、令牌、代理和证书。不要把完整密钥发到公共 Issue;必要时只保留前后少量字符用于识别。

4

4. 检查 Agent 绑定与权限

确认服务器已在 Agent【MCP】中启用,并检查当前权限模式。新发一条最小测试指令,只调用一个工具。

5

5. 用调用链定位请求

仍无法判断时,打开【设置】→【系统】→【开发者模式】,重启应用后复现一次,在调用链中查看 MCP 服务名、类型、输入、输出和状态。

应用案例:工具能看到,但 Agent 不调用

先在 MCP 详情中确认工具存在,再到 Agent【MCP】确认已经绑定。新发一条只要求调用该工具的最小指令;若停在等待状态,检查权限批准;若出现调用节点但返回错误,再看参数和服务端日志。不要一开始就重装服务器。

排错完成标准

能明确问题停在“服务器启动、连接认证、Agent 绑定、权限批准、工具执行”中的哪一环,并保留一条可重复的最小测试指令。

为什么同一配置在终端能运行,在 Cherry Studio 中失败?

应用进程与登录终端的环境变量和 PATH 可能不同。把服务明确需要的环境变量写进 MCP 配置,并确认命令是应用可以找到的可执行文件。

应该删除并重新添加服务器吗?

先看日志并逐项修正。只有配置已经混乱、来源也能重新取得时再删除重建;删除前保存不含密钥的配置副本。

最后更新于

这有帮助吗?