跳到主要内容

模型上下文协议（MCP）

OPL 数据空间从 v0.6.31 开始原生支持 MCP（Model Context Protocol）。本页说明如何快速启用、在生产环境中更稳妥地接入，以及如何排查常见问题。

信息

需要 OPL 数据空间 v0.6.31+。

前置要求：WEBUI_SECRET_KEY

在 Docker 部署中，你必须设置 WEBUI_SECRET_KEY 环境变量。否则，依赖 OAuth 的 MCP 工具（例如 Notion）会在容器重启或重建后失去令牌解密能力，反复报出 Error decrypting tokens，导致你每次都要重新授权。

快速开始​

  1. 打开 ⚙️ Admin Settings → External Tools。
  2. 点击 +（Add Server）。
  3. 将 Type 设为 MCP (Streamable HTTP)。
  4. 填写 Server URL 与认证信息。
  5. 点击 Save；如果界面提示，重启 OPL 数据空间。

完成后，你就可以在 OPL 数据空间中调用这个 MCP 服务器暴露出来的工具。

常见错误：连接类型选错

如果你接入的是 MCP 服务器，Type 必须选择 MCP (Streamable HTTP)，而不是 OpenAPI。

把带有 mcpServers 的 MCP 配置 JSON 填进 OpenAPI 连接，前端可能直接崩溃，或者进入无限 loading。若已出现这种情况：

  1. 先在 Admin Settings 中禁用或删除这个异常连接。
  2. 然后重新添加，并把 Type 正确设置为 MCP。

什么时候用 MCP，什么时候用 OpenAPI​

提示

对大多数部署来说，OpenAPI 仍然是优先推荐的集成方式。

优先选择 OpenAPI，如果你更看重：

  • 企业级接入能力：更成熟的 SSO、API 网关、审计、配额、类型化 SDK。
  • 运行稳定性：标准 HTTP 动词、幂等、缓存、更清晰的错误码。
  • 可观测性：更容易接入 tracing、策略控制和平台治理。

优先选择 MCP (Streamable HTTP)，如果你需要：

  • 复用团队已经在使用的 MCP 工具协议。
  • 基于 HTTP 的流式协议通信。

这里说的是 MCP 传输层的 streaming，不是 OPL 数据空间的 UI 事件系统；后者只适用于原生 Python 工具。

你不必二选一。很多团队会在内部暴露 OpenAPI，再在边缘为特定客户端包装 MCP。

注意

浏览器环境下的多用户部署，会显著增加 CORS / CSRF、按用户隔离、重连与令牌生命周期管理的复杂度。在把 MCP 暴露给外部之前，请先评估你的认证、代理和限流策略。

配置建议​

认证模式​

  • None：适合本地 MCP 服务器，或无需令牌的内网环境。
    • 除非你的服务器明确要求 token，否则建议默认选它。若误选 Bearer 且未填 key， OPL 数据空间会发送空的 Authorization: Bearer 头，很多服务器会立刻拒绝连接。
  • Bearer：仅在 MCP 服务器要求固定 API Token 时使用。必须填写 Key。
  • OAuth 2.1：使用动态客户端注册（DCR）。当 MCP 服务端支持自动注册 OAuth client 时优先使用。
  • OAuth 2.1 (Static)：使用预先创建好的 client ID / client secret。适合不支持 DCR 的提供方，或你的安全团队要求手工管理凭据的场景。
如何在 OAuth 2.1 与 OAuth 2.1 (Static) 间选择
  • 服务端支持 DCR 时，先试 OAuth 2.1。
  • 你已经从 IdP 拿到固定凭据，且希望 OPL 数据空间直接使用它们时，改用 OAuth 2.1 (Static)。

OAuth 2.1（Static）配置步骤​

  1. 打开 Admin Settings → External Tools。
  2. 点击 +（Add Server）。
  3. 将 Type 设为 MCP (Streamable HTTP)。
  4. 输入 MCP 服务器 URL。
  5. 在 Auth 中选择 OAuth 2.1 (Static)。
  6. 填写 Client ID 和 Client Secret。
  7. 点击 Register Client。
  8. 点击 Save。

保存后：

  1. 打开任意聊天。
  2. 点击 + → Integrations → Tools。
  3. 启用这个 MCP 工具。
  4. 在浏览器跳转中完成 OAuth 授权。
信息

oauth_2.1 与 oauth_2.1_static 都需要点击 Register Client。静态模式下， OPL 数据空间会使用你提供的 client 凭据和服务器元数据发现机制，不会进行动态客户端注册。

OAuth 2.1 工具不要设为默认工具

不要把 OAuth 2.1 的 MCP 工具设成模型的默认/预启用工具。 这类工具第一次使用时需要浏览器重定向、用户授权和回调，无法在一次普通聊天请求的后台“静默完成”。

如果用户尚未授权，或 refresh token 已失效，而这个工具又被默认挂在模型上，那么工具调用通常会失败，并显示 Failed to connect to MCP server。

正确做法是：让用户在具体聊天里通过输入框旁边的 ➕ 手动启用工具，这会先触发授权流程。完成首次授权后，后续令牌刷新通常可以自动进行。

连接地址​

如果 OPL 数据空间运行在 Docker 中，而你的 MCP 服务端运行在宿主机上：

  • 不要用 localhost
  • 改用 http://host.docker.internal:<port>

例如：http://host.docker.internal:3000/sse

Function Name Filter List​

这个字段用于限制哪些工具会暴露给 LLM。

  • 默认行为：留空时会暴露全部工具。
  • 兼容性绕过：如果留空时你遇到连接异常，可以尝试只填一个英文逗号 ,。这样系统会把它当作“合法但为空”的过滤列表，在某些解析边界条件下能绕开问题。

故障排查​

“Failed to connect to MCP server”​

症状： 设置页里的 Verify Connection 显示 Connected，但聊天实际调用工具时报错 Failed to connect to MCP server。

排查顺序：

  1. 检查认证模式。若服务端不需要 token，就不要选择 Bearer。
  2. 如果 Function Name Filter List 为空，尝试填入一个逗号 ,。
  3. 如果这个工具使用 OAuth 2.1，而且被设成了模型默认工具，请把它从默认工具里移除，改为按聊天手动启用。

添加 External Tool 后前端一直 loading​

症状： 添加连接后页面卡在 loading spinner，浏览器控制台常见错误是 Cannot convert undefined or null to object at Object.entries。

原因： 你很可能把 MCP 服务器 按 OpenAPI 类型配置了，或者把 MCP 风格 JSON 粘进了 OpenAPI 连接。

解决办法：

  1. 打开 Admin Settings → External Tools。
  2. 禁用或删除这个异常连接。
  3. 刷新页面。
  4. 按正确的 Type = MCP (Streamable HTTP) 重新添加。

常见问题​

支持 stdio 或 SSE 吗？​

OPL 数据空间当前原生支持的是 Streamable HTTP 形式的 MCP。原因很直接： OPL 数据空间是一个 Web 化、多租户 的系统，不是本地桌面进程。浏览器环境本身对长连接、用户隔离与安全边界有更严格的限制，直接维护 stdio 或传统 SSE 连接并不理想。

如果你需要接入这类 MCP 服务，可以使用 mcpo。它可以把基于 stdio 或 SSE 的 MCP 服务转成 OpenAPI 兼容接口。

这里的 MCP 支持稳定吗？​

可以使用，而且持续在改进。但整个 MCP 生态本身还在快速演进，偶发的破坏性变化仍有可能出现。

可以混用 OpenAPI 和 MCP 工具吗？​

可以。很多团队会同时使用这两种方式。