Skip to main content

Model Context Protocol (MCP)

Open WebUI natively supports MCP (Model Context Protocol) starting in v0.6.31. This page shows how to enable it quickly, harden it for production, and troubleshoot common snags.

info

Requires Open WebUI v0.6.31+.

Prerequisite: WEBUI_SECRET_KEY

You MUST set the WEBUI_SECRET_KEY environment variable in your Docker setup. Without it, OAuth-connected MCP tools (like Notion) will break every time you restart or recreate the container (Error: Error decrypting tokens), forcing you to re-authenticate everything.

๐Ÿš€ Quick startโ€‹

  1. Open โš™๏ธ Admin Settings โ†’ External Tools.
  2. Click + (Add Server).
  3. Set Type to MCP (Streamable HTTP).
  4. Enter your Server URL and Auth details (OAuth 2.1, if required).
  5. Save. If prompted, restart Open WebUI.

You can now call tools exposed by your MCP server from Open WebUI.

๐Ÿงญ When to use MCP vs OpenAPIโ€‹

tip

For most deployments, OpenAPI remains the preferred integration path.

Choose OpenAPI if you want:

  • Enterprise readiness: deep SSO, API gateways, audit, quotas, typed SDKs.
  • Operational resilience: standard HTTP verbs, idempotency, caching, rich error codes.
  • Observability: first-class tracing and policy integration.

Choose MCP (Streamable HTTP) if you need:

  • A common tool protocol already used by your MCP servers/clients.
  • Streamed tool events over HTTP with emerging ecosystem support.

You donโ€™t have to pick one: many teams expose OpenAPI internally and wrap MCP at the edge for specific clients.

warning

Browser-based, multi-user deployments increase the surface area (CORS/CSRF, per-user isolation, reconnects). Review your orgโ€™s auth, proxy, and rate-limiting policies before exposing MCP externally.

โ“ FAQโ€‹

Do you support stdio or SSE transports?

Native MCP support in Open WebUI is Streamable HTTP only. This design choice reflects our architecture: Open WebUI is a web-based, multi-tenant environment, not a local desktop process.

Browsers operate within strict sandboxed and event-driven HTTP constraints, making long-lived stdio or SSE connections difficult to maintain securely across users and sessions.

If you need to bridge those other MCP transports, check out mcpo โ€” an open-source proxy that translates stdio or SSE-based MCP servers into OpenAPI-compatible endpoints. It effectively lets you run traditional MCP tools inside Open WebUI without modifying their transport layer.

Is MCP considered stable here?

Supported and improving. The broader ecosystem is still evolving; expect occasional breaking changes.

Can I mix OpenAPI and MCP tools?

Yes. Many deployments do both.