> 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）](https://modelcontextprotocol.io) 集成让你的角色在对话中使用来自 MCP 服务器的工具。你的角色可以：

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

这让你的角色可以查找数据、搜索知识源，或在你的系统中触发操作，而无需为每个服务单独进行自定义集成。

### 前提条件

你的 MCP 服务器必须：

* 可通过 **公共 HTTPS**访问。本地服务器（stdio）和位于私有网络上的服务器不受支持。
* 使用 **可流式 HTTP** 传输。SSE 作为旧版回退方案受支持。
* 通过 **静态 HTTP 请求头** （Bearer 令牌、API 密钥）， **OAuth**，或无需认证。

### 添加 MCP 服务器

1. 在 Playground 中打开你的角色并进入 **MCP 和 APIs** 选项卡。
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 会对提供方的令牌进行加密存储并自动刷新。&#x20;

如果提供方使授权失效（令牌过期且未续期、密码更改、管理员撤销应用），状态会变为 **需要重新连接** ，并且服务器的工具会在新的会话中消失，直到你点击 **重新连接**.

#### 角色以谁的身份执行

你，角色所有者，只需连接一次账户。所有与该角色对话的人都通过这一份授权执行——同样的信任模型，就像静态请求头一样。

{% hint style="warning" %}
对于一个 **公开** 角色，陌生人可以在你的已连接账户下触发工具。请批准提供方提供的最小权限范围，并优先连接专用账户而不是你的个人账户。
{% endhint %}

#### 断开连接

**断开连接** 会撤销与提供方的授权并删除已存储的令牌；服务器配置会保留，因此你以后可以重新连接。 **删除** 会移除服务器、其令牌以及它与角色的连接。把认证方式切回请求头也会断开连接。并非每个提供方都支持远程撤销。要确定某个授权已失效，也请在提供方自己的安全设置中撤销它。

### 兼容的服务器&#x20;

任何使用静态请求头、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.