> For the complete documentation index, see [llms.txt](https://docs.cherryai.com.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cherryai.com.cn/advanced-basic/extensions/mcp/troubleshooting.md).

# MCP 排错

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

<figure><img src="/files/m1gKARdraSoSIKXNZThL" alt="从服务器启动、运行环境、认证网络到 Agent 绑定和调用链的 MCP 排错流程图"><figcaption><p>按顺序检查，先确认服务器本身能运行，最后再看 Agent 调用链。</p></figcaption></figure>

## 快速判断

| 现象               | 先检查                 | 常见原因                 |
| ---------------- | ------------------- | -------------------- |
| 服务器无法启动          | 【设置】→【MCP】→服务器详情→日志 | 命令不存在、参数错误、环境变量缺失    |
| 远程连接失败           | URL、网络代理、认证         | 地址协议错误、服务不可达、令牌失效    |
| 服务器正常但没有工具       | 服务器详情中的工具列表         | 服务未返回工具或权限不足         |
| 工具存在但 Agent 不会调用 | Agent【MCP】          | 未绑定、工具关闭、配置未从下一条消息生效 |
| 调用停在等待           | Agent 权限请求和右侧【状态】   | 需要人工批准或后台任务未完成       |
| 调用返回异常           | 调用链的输入、输出和状态        | 参数不符合工具定义、服务端错误      |

## 排查顺序

{% stepper %}
{% step %}

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

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

{% step %}

### 2. 检查运行环境

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

{% step %}

### 3. 检查认证与网络

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

{% step %}

### 4. 检查 Agent 绑定与权限

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

{% step %}

### 5. 用调用链定位请求

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

## 应用案例：工具能看到，但 Agent 不调用

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

### 排错完成标准

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

{% hint style="danger" %}
分享日志前删除 API Key、Authorization、邮箱、本地用户名、完整文件路径和业务数据。能用占位符说明的问题，不要上传真实凭据。
{% endhint %}

<details>

<summary>为什么同一配置在终端能运行，在 Cherry Studio 中失败？</summary>

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

</details>

<details>

<summary>应该删除并重新添加服务器吗？</summary>

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

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.cherryai.com.cn/advanced-basic/extensions/mcp/troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.