> 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/docs/zhong-wen-fan-ti/advanced-basic/extensions/mcp/troubleshooting.md).

# MCP 排錯

MCP 問題通常喺四個環節出現：服務器未啟動、運行環境唔完整、認證或者地址錯誤、Agent 未有綁定。跟住次序排查，會比反覆重裝快好多。

<figure><img src="/files/d79c458123f30c98d216324d72730e674f3d34c4" 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/docs/zhong-wen-fan-ti/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.