> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/convai-playground/character-customization/mcp-servers.md).

# MCP 服务器

通过 MCP 服务器将你的角色连接到工具和服务，以增强能力。

{% embed url="<https://www.youtube.com/watch?v=Q4xLERLR2Eg>" %}

此 [模型上下文协议（MCP）](https://modelcontextprotocol.io) 集成功能可让你的角色在对话中使用 MCP 服务器提供的工具。你的角色可以：

* 连接到你托管或订阅的任意兼容 MCP 的服务器
* 在每次对话开始时自动发现服务器提供的工具
* 在对话过程中调用工具，并在回复中使用调用结果

这样，你的角色就能查询数据、搜索知识库或触发系统中的操作，无需为每项服务单独进行定制集成。

### 前提条件

你的 MCP 服务器必须：

* 可通过 **公共 HTTPS**访问。本地服务器（stdio）和专用网络上的服务器不受支持。
* 使用 **Streamable HTTP** 传输协议。也支持将 SSE 作为旧版回退方案。
* 通过以下方式进行身份验证： **静态 HTTP 标头** （Bearer 令牌、API 密钥）、 **OAuth**或无需身份验证。

### 添加 MCP 服务器

1. 在 Playground 中打开你的角色，然后前往 **MCP 和 API** 选项卡。
2. 点击 **创建服务器**.
3. 填写服务器设置：

| 字段      | 备注                                                                                                                                     |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| 名称      | 显示在工具列表中。简短且描述清晰。                                                                                                                      |
| 说明      | 可选，供你自己备注。                                                                                                                             |
| 服务器 URL | 完整的 MCP 端点，包含路径，通常以 `/mcp`.                                                                                                            |
| 协议      | Streamable HTTP（推荐）。仅当你的服务器不支持 Streamable HTTP 时才使用 SSE。                                                                               |
| 授权      | <p><strong>HTTP 标头</strong>：随每个请求发送的名称/值对，例如 <code>Authorization: Bearer \<token></code>.<br><strong>OAuth</strong>：登录提供方，而不是输入密钥。</p> |
| 超时      | 单次工具调用的最长等待时间（1–300 秒，默认 30 秒）。请设置较短的时间，因为工具调用完成前，角色无法回复。                                                                              |

4. “ **可用工具** ”部分会连接到你的服务器，并列出服务器提供的工具。你也可以在此测试连接：如果服务器无法访问或身份验证标头有误，这里会显示相应错误。
5. 取消选中角色不应使用的工具。只有选中的工具才会提供给 LLM。
6. 启用 **连接到此角色** 并点击 **保存**.

服务器在账户级别注册：同一台服务器可以连接到多个角色。 **断开连接** 会从当前角色中移除服务器； **删除** 会将其从你的账户中移除。

{% hint style="info" %}
工具会在对话会话开始时发现，而不是在会话进行中发现。添加或编辑服务器后，请先开始一个新会话（重置 Playground 聊天会话），再进行测试。所有配置更改都会从下一次会话开始生效。
{% endhint %}

### 使用 OAuth 连接服务器

有些 MCP 服务器无需粘贴 API 密钥：你只需登录提供商进行身份验证，就像将应用连接到 Notion 或 Linear 工作区一样。对于这类服务器，请将身份验证方式设为 **OAuth** ，而不是输入请求头。

1. 在服务器表单的 **身份验证** 部分中，选择 **OAuth**.
2. 点击 **连接账户**。系统会弹出提供商的登录页面；登录并批准请求的访问权限。
3. 弹出窗口会自动关闭，状态会显示 **已连接**，并显示提供商授予的权限范围。
4. 接下来与其他服务器的操作相同：检查工具列表，启用 **连接到此角色**，然后保存。

对于大多数服务器，整个流程到此结束——Convai 会自动向提供商注册。

#### 需要注册应用的提供商

有些提供商（Google 和大多数企业身份系统）不允许自动注册；连接时会失败并提示客户端或注册错误。对于这类提供商：

1. 在提供商的开发者控制台中创建 OAuth 应用。
2. 将 `https://api.convai.com/mcp/oauth/callback` 注册为应用的重定向/回调 URL。
3. 在服务器表单中，展开 **提供商要求注册应用？**，输入应用的 **客户端 ID** （以及 **客户端密钥**，如果提供商有提供），然后点击 **连接账户**.

#### 连接后

Convai 会加密存储提供商的令牌，并自动刷新。

如果提供商撤销了授权（令牌过期且未续期、密码更改，或管理员撤销了应用），状态会变为 **需要重新连接** ，在你点击 **重新连接**.

#### 角色以谁的身份操作

你（角色所有者）只需连接一次账户。所有与该角色交谈的人都会通过这项授权进行操作，其信任模型与静态请求头相同。

{% hint style="warning" %}
对于 **公开** 角色，陌生人可以通过你已连接的账户触发工具。请批准提供商允许的最小权限范围，并尽量连接专用账户，而非个人账户。
{% endhint %}

#### 断开连接

**断开连接** 会向提供方撤销授权，并删除已存储的令牌；服务器配置会保留，因此你之后可以重新连接。 **删除** 会移除服务器、其令牌及其角色连接。将身份验证方式切换回标头也会断开连接。并非所有提供方都支持远程撤销。若要确保授权已失效，还应在提供方自己的安全设置中撤销。

### 兼容的服务器

任何使用静态标头、OAuth 或完全无需身份验证的 MCP 服务器。可以是你使用 MCP SDK（[Python](https://github.com/modelcontextprotocol/python-sdk), [TypeScript](https://github.com/modelcontextprotocol/typescript-sdk)、FastMCP）自行构建的服务器，也可以是接受在标头中传入 API 密钥的托管服务器，例如 [Firecrawl](https://docs.firecrawl.dev/mcp), [Context7](https://context7.com), [GitHub](https://github.com/github/github-mcp-server) （个人访问令牌），或基于 OAuth 的服务器，例如 [Notion](https://developers.notion.com/docs/mcp) 或 [Linear](https://linear.app/docs/mcp)。请查阅提供方的文档，了解端点 URL 和身份验证方式。

#### 对话中的工具调用如何运作

会话开始时，Convai 会连接到每个已附加的服务器并获取其工具列表。如果服务器不可用或响应缓慢，超过较短的连接时限后就会跳过该服务器，对话会在不使用其工具的情况下开始；服务器故障不会妨碍角色交谈。

对话过程中，LLM 会根据工具的名称和描述决定何时调用工具。调用时：

* **回复会等待工具调用完成。** 在语音对话中，工具运行期间角色会保持沉默。请确保工具运行迅速，最好在几秒内完成。
* 如果调用超时或出错，角色会收到通知并作出相应回应。
* 一轮对话中可以调用多个工具；这些调用会并行运行。

#### 编写适用于语音交互的工具

描述本身就是提示词，因此，用一句清晰的话说明工具的功能和适用时机，胜过详尽的规格说明。应提供少量工具，而不是大量工具（工具集过大会拖慢模型并导致选错工具）。快速返回简短结果；如果失败，应返回一条消息（“未找到与该电子邮件对应的订单”），而不是空结果。

{% hint style="info" %}
工具权限在对话开始前设置：每个工具的勾选清单就是授权界面。每次调用都不会弹出授权提示，因此只启用你愿意在任何一轮对话中被调用的工具。
{% endhint %}

### 安全与数据

#### 凭据

授权标头的值会在静态存储时加密，且仅用于连接到你的服务器。OAuth 令牌也会在静态存储时加密，并自动刷新；如需撤销访问权限，请使用 **断开连接**.

#### 谁能触发工具

无论是谁在与角色交谈，工具都会使用你配置的凭据运行。

{% hint style="warning" %}
如果角色是 **公开的**，任何与其交谈的人都能使用你的凭据触发工具调用。只附加适合向陌生人开放的工具：只读、设有速率限制且不包含敏感数据。
{% endhint %}

#### 数据流

工具参数（可能包含用户刚刚说的内容）会发送到你的 MCP 服务器，返回结果则会进入模型的上下文。这些数据会离开 Convai，并受你服务器自身的日志记录和数据保留政策约束。工具描述和结果属于不可信文本，会进入模型提示词；恶意服务器可能会试图操控你的角色。请只连接你控制或信任的服务器。

### 故障排查

| 症状                | 原因及解决方法                                                                                                            |
| ----------------- | ------------------------------------------------------------------------------------------------------------------ |
| 加载工具：401 / 未授权    | 服务器拒绝了你的身份验证标头。请检查标头名称、值的格式（许多服务器需要 `Bearer` 前缀），并确认令牌处于有效状态。                                                      |
| 加载工具：超时 / 连接错误    | 该 URL 不是可访问的 MCP 端点。请包含 MCP 路径（通常为 `/mcp`）；确认传输方式；并确认该地址可从公网访问（`curl -i <url>` 有响应）。系统会拒绝私有地址或 localhost 地址；请使用隧道。 |
| 加载工具：0 个工具        | 连接成功，但服务器未注册任何工具。请检查服务器端。                                                                                          |
| 工具未出现在对话中         | 会话在你保存之前就已启动。请启动新会话。如果问题仍然存在：检查「已连接」开关是否已开启，并确认至少勾选了一个工具。                                                          |
| 角色提示工具调用失败        | 超时（默认 30 秒）、服务器端错误（检查服务器日志中的 `tools/call`），或凭据已过期（重新运行 Load tools；如果那里显示 401，即可确认）。                                |
| “无法解密已存储的凭据”      | 无法再读取已保存的标头值。配置仍然完好；请重新输入这些值并保存。                                                                                   |
| 工具被忽略或误用          | 完善工具描述，减少启用的工具数量，添加提示说明（“对于订单问题，请使用 `lookup_order`”），并在服务器端精简过长的结果。                                                |
| 连接账户：没有任何反应       | 浏览器阻止了弹出窗口。请允许 convai.com 弹出窗口，然后再次点击「连接」。                                                                         |
| 连接失败，出现注册错误或客户端错误 | 该提供方不允许自动注册。请参阅「需要注册应用的提供方」。                                                                                       |
| 状态显示“需要重新连接”      | 提供方使授权失效了（过期、密码更改或管理员撤销）。点击 **重新连接** 并再次授权；工具将在下一个会话中恢复。                                                           |


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/convai-playground/character-customization/mcp-servers.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
