跳到主要内容

模型上下文协议 (MCP)

Open WebUI 自 v0.6.31 版本起原生支持 MCP (Model Context Protocol)。本页为您介绍如何快速启用 MCP、在生产环境中对其进行加固，以及如何排除常见故障。

信息

需要 Open WebUI 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（服务器 URL） 和 Auth（身份验证） 信息（若有要求，配置 OAuth 2.1）。
  5. 点击 Save（保存）。如果系统提示，请重启 Open WebUI。

您现在即可从 Open WebUI 中调用由 MCP 服务器暴露出来的各种工具了。

常见错误：连接类型错误

如果您在添加 MCP 服务器，请务必确保 Type（类型） 被设置为 MCP (Streamable HTTP)，而不是 OpenAPI。

在 OpenAPI 连接类型中输入 MCP 风格的配置参数（例如在 JSON 中包含 mcpServers）会导致前端 UI 界面崩溃或展示出无限加载的白屏。如果您不幸遇到了这一问题，请按以下步骤修复：

  1. 通过“管理员设置”界面，禁用有问题的工具连接。
  2. 重新添加它，并确保将正确的 Type（类型） 设置为 MCP。

🧭 何时选用 MCP 或 OpenAPI​

提示

对于绝大多数生产部署环境，OpenAPI 仍然是首选的集成路径。

如果您需要以下特性，请选择 OpenAPI：

  • 企业级就绪：深度 SSO 单点登录、API 网关、审计日志、调用配额限制以及类型化 SDK。
  • 运营韧性：标准的 HTTP 动作方法、幂等性设计、缓存机制及丰富的错误返回码。
  • 可观测性：一流的调用链路追踪与安全策略集成。

如果您有以下要求，请选择 MCP (Streamable HTTP)：

  • 您的 MCP 服务器/客户端已经广泛使用了通用的工具调用协议。
  • 需要基于 HTTP 的流式协议通信（注意：这指的是 MCP 传输协议层面的流式传输，而不是 Open WebUI 针对原生 Python 工具所特有的 UI 事件系统）。

您并非必须二选一：很多团队的做法是在内部暴露 OpenAPI 接口，而在边界网络上为特定的客户端封装 MCP。

注意

基于浏览器运行的多用户部署环境会带来更大的安全漏洞暴露面（CORS/CSRF、用户间的物理隔离、重连机制等）。在向公网公开暴露 MCP 服务器之前，请严格评估您组织的安全审计、反向代理与频次限制策略。

⚙️ 配置最佳实践​

身份验证模式​

  • None（无）：适用于不需要任何 Token 验证的本地 MCP 服务器或内网环境。
    • ⚠️ 重要提示：除非您的服务器明确要求 Token 校验，否则请默认选择 “None”。在未提供 API 密钥的情况下选择 “Bearer” 会向服务器发送一个空的 Authorization 请求头（Authorization: Bearer），这会导致很多 MCP 服务器立刻拒绝连接。
  • Bearer：仅在您的 MCP 服务器需要特定的 API Token 时选择。您必须在 "Key" 字段中填入相应的值。
  • OAuth 2.1：使用动态客户端注册 (Dynamic Client Registration, DCR) 机制。当您的 MCP 服务器支持自动注册 OAuth 客户端时，这是最佳选择。
  • OAuth 2.1 (Static)：使用预先创建的客户端 ID (Client ID) 与客户端密钥 (Client Secret)。当您的提供商不支持 DCR，或者您的安全审计团队要求必须手动管理和审核调用凭证时，这是最佳选择。
在 OAuth 2.1 与 OAuth 2.1 (Static) 之间进行选择
  • 如果您的服务器支持 DCR，请先尝试使用 OAuth 2.1。
  • 如果您已经从您的身份提供商 (IdP) 处获取了现成的凭证，并希望 Open WebUI 直接使用这些凭证，请选择 OAuth 2.1 (Static)。

OAuth 2.1 (静态) 设置​

当您已经从您的身份提供商处拥有了 Client ID / Client Secret 时，请使用此方式。

  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. （可选） 如果您的身份提供商与 MCP 资源服务器不在同一台主机上，请输入 OAuth Server URL。留空时，Open WebUI 将从 MCP 服务器 URL 中获取 OAuth 发现文档；当设置此项时，服务发现与静态凭证注册都将改为请求该 URL。这对于由 MCP 服务器代理企业独立外部 IdP 的架构非常有用。
  8. 点击 Register Client（注册客户端）。
  9. 点击 Save 并保存。

保存完成后：

  1. 打开一个聊天窗口。
  2. 点击 + → Integrations（集成） → Tools（工具）。
  3. 勾选并启用您的 MCP 工具。
  4. 在浏览器的重定向页面中，完成 OAuth 授权确认流。
信息

Register Client 步骤对于 oauth_2.1 和 oauth_2.1_static 都是必需的。配置静态身份验证时，Open WebUI 将使用您提供的凭据和发现的服务器元数据（不进行动态客户端注册）。

资源指示器 (RFC 8707)

如果 MCP 服务器在它的 RFC 9728 受保护资源元数据文档 (/.well-known/oauth-protected-resource) 中发布了 resource 字段，Open WebUI 将在服务发现期间捕获它，并将其作为 resource 参数转发给授权重定向、Token 交换以及每次 Refresh-token 刷新调用。这可以确保正确设置签发 Token 中的 aud (Audience) 声明，也是那些按照 RFC 8707 规范严格验证接收对象的身份提供商所强制要求的。

在 Open WebUI 侧无需进行任何手动配置 —— 资源指示器会自动发现。如果您的 IdP 因为 invalid_audience 或类似报错而拒绝对 MCP 工具的调用，请先检查您的 MCP 服务器的受保护资源元数据文档是否公布了正确的 resource URL。

⚠️ OAuth 2.1 工具无法设为默认工具

千万不要将 OAuth 2.1 MCP 工具设置为模型的默认/预启用工具。 OAuth 2.1 的授权流需要一次交互式的浏览器页面重定向（用户授权确认、重定向回调），这无法在用户聊天生成请求期间静默完成。

如果将 OAuth 2.1 工具设为默认工具，而用户此前尚未进行身份验证（或者其 Refresh Token 已过期），工具调用将失败并抛出 "Failed to connect to MCP server"，因为后端无法在请求执行的中途发起基于浏览器的网页端认证流。

临时解决方法：用户应该在聊天输入框的 ➕ 按钮中，针对每次聊天对话手动启用 OAuth 2.1 工具。这会在工具被触发前拉起身份验证流程。一旦初始身份验证完成，后续的 Token 刷新就可以在后台自动执行。

连接 URL​

如果您在 Docker 中运行 Open WebUI，而您的 MCP 服务器运行在您的宿主机上：

  • 请使用 http://host.docker.internal:<端口号>（如 http://host.docker.internal:3000/sse）来代替 localhost。

自定义请求头​

MCP 与 OpenAPI 工具服务器连接都支持填入一个通用的 Headers 字段（接收一个 JSON 对象），该对象的内容会被合并到发出的每一次外部请求中。Header 的值支持一小部分模板 Token 占位符，它们会在请求时在服务端被解析展开。这允许您将同一个连接路由到针对不同用户、不同聊天或不同消息的后端逻辑，而无需分别创建单独的连接通道：

占位符 Token解析替换为
{{USER_ID}}发起调用的用户的 ID。
{{USER_NAME}}发起调用的用户的显示名称。
{{CHAT_ID}}当前的聊天 ID（在“验证连接”按钮等非聊天上下文中解析为空）。
{{MESSAGE_ID}}当前的消息 ID（在非聊天上下文中解析为空）。

未知的占位符将作为字面纯文本直接传递。非字符串类型的 Header 值会在被替换前被强制转换为字符串。在 Admin Settings → Connections → OpenAI 中，为 OpenAI 兼容的模型连接自定义请求头时，也支持完全相同的占位符替换，因此您可以使用此功能在上述两个模块中实现多租户路由或审计链路传播追踪。

函数名称过滤列表​

此字段可以限制向大语言模型 (LLM) 暴露哪些工具。

  • 默认状态：保持留空以暴露所有工具（在大多数情况下推荐如此）。
  • 临时解决方法：如果您在列表留空时遇到连接失败，可以尝试在该字段中加入一个英文字符逗号（,）。这会强制系统将其视为一个有效（但为空）的过滤器，有可能绕过某些解析上的 Bug。

故障排除​

“Failed to connect to MCP server”（连接 MCP 服务器失败）​

症状： 在聊天中使用工具时，即使在设置界面中点击 Verify Connection 按钮显示为“Connected（已连接）”，聊天界面依然报错 “Failed to connect to MCP server”。

解决方法：

  1. 检查身份验证：确保您没有在选择 Bearer 模式的同时让 Key 留空。如果不需要 Token，请将模式切换为 None。
  2. 过滤列表 Bug：如果“函数名称过滤列表 (Function Name Filter List)”为空，尝试在其中填入一个半角逗号（,）。
  3. OAuth 2.1 默认工具：如果报错的工具使用 OAuth 2.1 协议，且被设为了该模型的默认自动启用工具，这属于已知的局限。请将其从模型的默认工具中移除，让用户在聊天中按需手动勾选启用。

添加外部工具后无限加载​

症状： 添加了一个新的外部工具连接后，前端页面卡死在加载圈。浏览器控制台报错：Cannot convert undefined or null to object at Object.entries。

原因： 您很有可能在 OpenAPI 连接类型中配置了 MCP 服务器，或者在 OpenAPI 连接中输入了 MCP 风格的 JSON（包含了 mcpServers）。

解决方法：

  1. 打开 Admin Settings → External Tools（左侧边栏依然可以加载）。
  2. 将有问题的工具连接禁用或删除。
  3. 按快捷键强制刷新页面（Ctrl+F5）。
  4. 重新添加该连接，并务必确保 Type 被选择为 MCP (Streamable HTTP)。

❓ 常见问题​

你们支持 stdio 或 SSE 传输协议吗？

Open WebUI 对 MCP 的原生支持仅限 Streamable HTTP 协议。这一设计决策是由我们的系统架构决定的：Open WebUI 是一个基于 Web 的多租户集群环境，而不是本地运行的单机桌面进程。

浏览器运行在严格受限的沙箱化与事件驱动的 HTTP 约束中，这使得在不同用户与会话之间很难安全、长效地维持底层的 stdio 或 SSE 连接。

如果您需要将这些其他的 MCP 传输通道桥接进来，请关注社区开源项目 mcpo —— 这是一个可以将基于 stdio 或 SSE 的 MCP 服务器翻译为 OpenAPI 兼容端点的网关。它允许您在不修改传输层的情况下，将传统的 MCP 工具引入 Open WebUI 中运行。

这里的 MCP 支持被认为是稳定版吗？

已正式提供支持并在持续改进中。整个 MCP 生态系统依然处于快速迭代演进中，后续请做好可能会有非兼容性变更的心理准备。

我可以将 OpenAPI 与 MCP 工具混合搭配使用吗？

完全可以。许多生产环境部署都是两者并行使用的。

This content is for informational purposes only and does not constitute a warranty, guarantee, or contractual commitment. Open WebUI is provided "as is." See your license for applicable terms.