> 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 token、API 密钥）， **OAuth**，或无需认证进行身份验证。

### 添加 MCP 服务器

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

| 字段      | 说明                                                                                                                                     |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| 名称      | 显示在工具列表中。应简短且具有描述性。                                                                                                                    |
| 描述      | 可选，仅供你自己参考。                                                                                                                            |
| 服务器 URL | 完整的 MCP 端点，包括路径，通常以 `/mcp`.                                                                                                            |
| 协议      | 可流式 HTTP（推荐）。仅当你的服务器不支持可流式 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. 在服务器表单中展开 **需要已注册应用的提供方？**，输入应用的 **Client ID** （以及 **Client secret**，如果提供方有提供的话），然后点击 **连接账户**.

#### 连接后

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 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 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.convai.com/api-docs/zh/convai-playground/character-customization/mcp-servers.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.