MCP 服务器

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

该 模型上下文协议（MCP） 集成让你的角色在对话中使用来自 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。
授权	HTTP 头：随每个请求发送的键值对，例如 Authorization: Bearer <token>. OAuth：改为登录到提供方，而不是输入密钥。
超时	等待单次工具调用的最长秒数（1–300，默认 30）。请保持较低，因为工具调用完成前角色无法回复。

1. 该 可用工具 部分会连接到你的服务器并列出它公开的工具。这也是你的连接测试：无法访问的服务器或错误的认证头会在这里显示错误。
2. 取消勾选角色不应拥有的任何工具。只有勾选的工具才会提供给 LLM。
3. 打开 已连接到此角色 并点击 保存.

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

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

使用 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 会以加密方式存储提供方的令牌，并自动刷新。

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

角色以谁的身份行事

你，作为角色所有者，只需连接一次账户。所有与该角色对话的人都通过这一个授权来操作——与静态头相同的信任模型。

对于 公开 角色，陌生人可以在你的已连接账户下触发工具。请批准提供方提供的最小作用域，并优先连接专用账户而不是你的个人账户。

断开连接

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

兼容的服务器

任何使用静态头、OAuth 或完全无需认证的 MCP 服务器。它可以是你用 MCP SDK 自己构建的服务器（Python, TypeScript、FastMCP），也可以是接受头中的 API 密钥的托管服务器，例如 Firecrawl, Context7, GitHub （个人访问令牌），或者基于 OAuth 的服务器，例如 Notion 或 Linear。请查看提供方文档以获取端点 URL 和认证方式。

工具调用在对话中如何工作

在会话开始时，Convai 会连接到每个已附加的服务器并获取其工具列表。如果某个服务器宕机或响应缓慢，在短暂的连接预算耗尽后会被跳过，对话会在没有该服务器工具的情况下开始；服务器故障不会阻止你的角色说话。

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

• 回复会等待工具调用完成。 在语音模式下，工具运行期间角色会保持沉默。请保持工具快速，最好控制在几秒以内。
• 如果调用超时或出错，角色会被告知并作出相应回复。
• 一次轮次中可以调用多个工具；这些调用会并行运行。

编写适合语音的工具

描述就是提示词，所以用一句清晰的话说明工具做什么、何时使用，胜过详尽的规格说明。尽量少暴露工具，而不是很多工具（大量工具会拖慢模型并导致选错）。快速返回简短结果，并给出带消息的失败结果（“没有找到该邮箱的订单”），而不是空结果。

工具权限在对话前设定：每个工具的勾选框就是批准范围。不会有逐次调用的审批提示，所以只启用那些你愿意在任意轮次被调用的工具。

安全与数据

凭据

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

谁可以触发工具

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

如果角色是 公开，任何与它对话的人都可以使用你的凭据触发工具调用。只应附加那些对陌生人暴露也安全的工具：只读、限流、不包含敏感数据。

数据流

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

故障排除

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