> 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/en-us/advanced-basic/extensions/mcp.md).

# MCP and External Tools

MCP is the connection method that lets Agents use external tools and resources. Cherry Studio can manage MCP servers, built-in servers, service marketplaces, and some provider entry points, then bind connected servers to a specified Agent.

<figure><img src="/files/94c9036d258f9b5c1b2337e07393586ce87252cb" alt="MCP 设置页面中的服务器列表、搜索和添加入口"><figcaption><p>View server status centrally under [Settings] → [MCP]; first make sure a server runs properly on its own, then bind it to an Agent.</p></figcaption></figure>

## When MCP is needed

* The Agent needs to call services other than Cherry Studio’s built-in tools;
* The team already has databases, browsers, or business systems that provide MCP interfaces;
* You want the same external capabilities to be reused by multiple Agents;
* You need to provide tools, resources, or prompts to the model in a unified way.

Use Skills only when you need a fixed workflow, and bind the knowledge base directly when you only need to retrieve Cherry Studio’s knowledge base; there is no need to set up MCP extra just to be “more advanced.”

<figure><img src="/files/21e896d4dd3763ee7fd44b2393ba7ac6ea765090" alt="MCP 服务器的快速创建、从 JSON 导入和手动创建方式"><figcaption><p>If the service provider offers JSON, it can be imported directly; if there is no ready-made configuration, fill in the command or address manually.</p></figcaption></figure>

## Add server

Path: \[Settings] → \[MCP] → \[MCP Servers] → \[Add].

{% stepper %}
{% step %}

### 1. Confirm the connection method

Local commands usually use standard input/output; remote services usually provide SSE or a streamable HTTP address. Fill in the configuration according to what the service provider gives you; do not guess based on the name.
{% endstep %}

{% step %}

### 2. Fill in the configuration and check permissions

Local servers require commands, arguments, and environment variables; remote servers require a URL, and some services also require authorization. Before saving, confirm the command source and data scope.
{% endstep %}

{% step %}

### 3. Start and view tools

Enable the server, wait until the status is normal, then open the details to check the tools, resources, and prompts it provides. If the connection fails, first check the server logs.

In the tool list, expand a tool to view the full Markdown documentation, as well as the parameters, types, required flags, and enum values displayed hierarchically. Before calling it, first verify the required parameters; object or array parameters should be expanded layer by layer to avoid guessing the input format based only on the tool name.
{% endstep %}

{% step %}

### 4. Bind to Agent

Open \[Work] → Agent menu → \[Edit] → \[MCP], and enable this server. A server that is not started cannot be bound and used properly.
{% endstep %}
{% endstepper %}

## Built-in servers and service marketplace

\[Built-in MCP] provides common capabilities that can be installed or enabled directly; \[Service Marketplace] is used to manage third-party marketplace sources. Before installation, you still need to review the description, commands, environment variables, and permissions; a built-in entry does not mean all operations of the external service are risk-free.

## Configuration recommendations

| Configuration item    | Product default                                    | Suggested starting point                                             | Effect                                       | Applicable scenario                     | Notes                                                          |
| --------------------- | -------------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------- | --------------------------------------- | -------------------------------------------------------------- |
| Server status         | Decide according to the configuration after adding | Enable only one at a time and verify it                              | Control whether the server is available      | Initial access, troubleshooting         | Hard to locate when multiple services fail at the same time    |
| Agent binding         | Do not automatically bind all servers              | Bind only the servers required by the current Agent                  | Control the capability scope                 | Division of labor among multiple Agents | Avoid unrelated tools occupying context                        |
| Environment variables | Do not prefill keys                                | Use credentials with the minimum permissions required by the service | Provide authentication or runtime parameters | Private service                         | Cover sensitive content before taking screenshots or exporting |
| Tool approval         | Determined by the Agent permission mode            | Keep confirmation for write or billing tools                         | Prevent accidental operations                | Databases, files, external APIs         | Channel entry points can use a stricter mode                   |

## User case: connecting the project database to an analysis Agent

The administrator provides a read-only MCP connection. The user verifies that the server is working properly under \[Settings] → \[MCP], then binds it only to the “Data Analysis” Agent. The Agent uses the read-only tools to obtain data and writes the report to the working directory; tools that would update data are not enabled. In this way, even if the prompt is misunderstood, the business database will not be modified directly.

<details>

<summary>What is the difference between MCP and an API gateway?</summary>

MCP connects external tools to Cherry Studio; an API gateway exposes Cherry Studio’s model capabilities to other programs in API-compatible form. The data flow direction is opposite.

</details>

<details>

<summary>What should I do if the server shows connected, but the Agent still cannot find the tools?</summary>

Check whether the Agent is bound to that server, whether the tools have been disabled, and whether any permission requests are pending. After modifying the Agent configuration, send a new message so the runtime loads the new tools.

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