> 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.md).

# MCP 与外部工具

MCP 是让 Agent 使用外部工具和资源的连接方式。Cherry Studio 可以管理 MCP 服务器、内置服务器、服务市场和部分服务商入口，再把已连接的服务器绑定给指定 Agent。

<figure><img src="/files/lpCz9INBPt3zvdeqbBOJ" alt="MCP 设置页面中的服务器列表、搜索和添加入口"><figcaption><p>在【设置】→【MCP】统一查看服务器状态；先让一个服务器单独运行正常，再绑定给 Agent。</p></figcaption></figure>

## 什么时候需要 MCP

* Agent 需要调用 Cherry Studio 内置工具之外的服务；
* 团队已经有提供 MCP 接口的数据库、浏览器或业务系统；
* 希望同一套外部能力被多个 Agent 复用；
* 需要把工具、资源或提示词以统一方式提供给模型。

只需要固定流程时用技能，只需要检索 Cherry Studio 知识库时直接绑定知识库，不必为了“更高级”而额外搭建 MCP。

<figure><img src="/files/oKtEFpOzDF1t97MLI92A" alt="MCP 服务器的快速创建、从 JSON 导入和手动创建方式"><figcaption><p>有服务方提供的 JSON 时可直接导入；没有现成配置时再手动填写命令或地址。</p></figcaption></figure>

## 添加服务器

路径：【设置】→【MCP】→【MCP 服务器】→【添加】。

{% stepper %}
{% step %}

### 1. 确认连接方式

本地命令通常使用标准输入输出方式；远程服务通常提供 SSE 或可流式传输的 HTTP 地址。按照服务提供方给出的配置填写，不要凭名称猜测。
{% endstep %}

{% step %}

### 2. 填写配置并检查权限

本地服务器需要命令、参数和环境变量；远程服务器需要 URL，部分服务还需要授权。保存前确认命令来源和数据范围。
{% endstep %}

{% step %}

### 3. 启动并查看工具

启用服务器，等待状态正常，再打开详情检查它提供的工具、资源和提示词。连接失败时先看服务器日志。

在工具列表中展开某个工具，可以查看完整的 Markdown 说明，以及按层级展示的参数、类型、必填标记和枚举值。调用前先核对必填参数；对象或数组参数应逐层展开查看，避免只按工具名称猜测输入格式。
{% endstep %}

{% step %}

### 4. 绑定到 Agent

打开【工作】→ Agent 菜单→【编辑】→【MCP】，启用该服务器。未启动的服务器无法正常绑定使用。
{% endstep %}
{% endstepper %}

## 内置服务器与服务市场

【内置 MCP】提供可以直接安装或启用的常用能力；【服务市场】用于管理第三方市场来源。安装前仍要查看说明、命令、环境变量和权限，内置入口不代表外部服务的所有操作都没有风险。

## 配置建议

| 配置项      | 产品默认值          | 建议起点              | 作用        | 适用场景          | 注意事项         |
| -------- | -------------- | ----------------- | --------- | ------------- | ------------ |
| 服务器状态    | 新增后按配置决定       | 一次只启用一个并验证        | 控制服务器是否可用 | 初次接入、排错       | 多个服务同时失败时难定位 |
| Agent 绑定 | 不自动绑定所有服务器     | 只绑定当前 Agent 所需服务器 | 控制能力范围    | 多 Agent 分工    | 避免无关工具占用上下文  |
| 环境变量     | 不预填密钥          | 使用服务要求的最小权限凭据     | 提供认证或运行参数 | 私有服务          | 截图和导出前遮挡敏感内容 |
| 工具批准     | 由 Agent 权限模式决定 | 写入或计费工具保持确认       | 防止意外操作    | 数据库、文件、外部 API | 频道入口可使用更严格模式 |

## 用户案例：把项目数据库接给分析 Agent

管理员提供只读 MCP 连接，用户在【设置】→【MCP】验证服务器正常，再只绑定给“数据分析”Agent。Agent 使用只读工具取得数据，将报告写入工作目录；涉及更新数据的工具不启用。这样即使提示词出现误解，也不会直接修改业务库。

<details>

<summary>MCP 与 API 网关有什么区别？</summary>

MCP 是把外部工具接入 Cherry Studio；API 网关是把 Cherry Studio 的模型能力以兼容 API 提供给其他程序。数据流方向相反。

</details>

<details>

<summary>服务器显示已连接，Agent 仍找不到工具怎么办？</summary>

检查 Agent 是否绑定了该服务器、工具是否被关闭、权限请求是否待处理。修改 Agent 配置后，新发一条消息让运行时加载新工具。

</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.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.