> 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）和私有网络中的服务器。
* 使用 **可流式 HTTP** 传输。SSE 作为旧版回退方案受支持。
* 使用以下方式进行身份验证： **静态 HTTP 标头** （Bearer 令牌、API 密钥）， **OAuth**，或无需认证。

### 添加 MCP 服务器

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

| 字段            | 备注                                                                                                                                     |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| 名称            | 会显示在工具列表中。简短且具有描述性。                                                                                                                    |
| 说明            | 可选，仅供你自己参考。                                                                                                                            |
| 服务器 URL       | 完整的 MCP 端点，包括路径，通常以以下内容结尾： `/mcp`.                                                                                                     |
| 协议            | 可流式 HTTP（推荐）。仅当你的服务器不支持可流式 HTTP 时才使用 SSE。                                                                                              |
| Authorization | <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. Register `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 %}

### 安全与数据

#### 凭据

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

#### 谁可以触发工具

工具会使用你配置的凭据运行，不管是谁在与角色对话。

{% hint style="warning" %}
如果角色是 **公开**，那么与它对话的任何人都可以使用你的凭据触发工具调用。只附加那些对陌生人暴露也安全的工具：只读、限流、且不含敏感数据。
{% endhint %}

#### 数据流

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

### 故障排除

| 症状             | 原因与修复                                                                                                        |
| -------------- | ------------------------------------------------------------------------------------------------------------ |
| 加载工具：401 / 未授权 | 服务器拒绝了你的认证标头。检查标头名称、值的格式（许多服务器需要 `Bearer` 前缀），以及令牌是否有效。                                                      |
| 加载工具：超时 / 连接错误 | 该 URL 不是可访问的 MCP 端点。请包含 MCP 路径（通常为 `/mcp`）；确认传输方式；确认它可公开访问（`curl -i <url>` 有响应）。私有/localhost URL 会被拒绝；请使用隧道。 |
| 加载工具：0 个工具     | 连接成功，但服务器没有注册任何工具。请检查服务器端。                                                                                   |
| 工具没有出现在对话中     | 会话是在你保存之前开始的。请开始一个新会话。如果问题仍然存在：检查“已连接”开关是否已开启，并且至少勾选了一个工具。                                                   |
| 角色说工具失败了       | 超时（默认 30 秒）、服务器端错误（查看你的服务器日志中是否有 `tools/call`），或者凭据已过期（重新运行“加载工具”；若那里显示 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.