Open WebUI MCP Setup Guide 2026: Connect MCP Servers, OAuth & WEBUI_SECRET_KEY
A practical guide to connecting an MCP server to Open WebUI, with Streamable HTTP, Docker networking, OAuth, persistent secrets, permissions and troubleshooting.
What you need before starting
Open WebUI documents native MCP support starting with version 0.6.31. Native MCP connections use Streamable HTTP, and adding an MCP server is an administrator-only operation.
- Open WebUI 0.6.31 or newer.
- An MCP server with a Streamable HTTP endpoint.
- Administrator access to Open WebUI.
- A model with reliable native tool-calling capability.
- Persistent Open WebUI application data.
MCP supplies the tool interface; it does not make a weak model better at selecting tools or generating valid arguments. If the connection works but tool use is poor, test a model known for reliable native tool calling.
Native MCP or mcpo?
Native MCP is the direct option when your server exposes Streamable HTTP. Open WebUI also maintains mcpo, an MCP-to-OpenAPI bridge that can help when an existing MCP server uses transports such as stdio or SSE.
| Option | Use it when | Transport |
|---|---|---|
| Native MCP | Your server exposes Streamable HTTP | Streamable HTTP |
| mcpo | You need to bridge another MCP transport | Bridge-dependent |
If the server already supports Streamable HTTP, native MCP is normally the simpler path.
Add the MCP server
- Sign in as an Open WebUI administrator.
- Open Settings > Admin > Integrations.
- Under External Tool Servers, choose + Add Connection.
- Set the type to MCP (Streamable HTTP).
- Enter the MCP server URL.
- Select the authentication method required by the server.
- Save the connection.
The connection type matters. Do not enter MCP-style configuration into an OpenAPI connection. Open WebUI documents an infinite-loading or frontend-error failure mode when the wrong connection type is used.
Authentication choices
None
Use None when the server is trusted on your internal network and does not require a token.
Bearer
Use Bearer only when the MCP server requires a specific API token, and provide the required key.
OAuth 2.1
Use OAuth 2.1 when the server supports dynamic client registration. Open WebUI can discover the authorization metadata and perform the registration and authorization flow.
OAuth 2.1 Static
Use the static option when you already have client credentials from your identity provider or your organization requires manually managed credentials.
OAuth persistence and reauthentication
OAuth state must remain decryptable after an Open WebUI restart or container recreation. If OAuth suddenly breaks after recreating a container, check that the deployment's persistent Open WebUI secret configuration did not change and that the application data volume was preserved.
Open WebUI's current documentation also notes that standard launch methods can persist a generated key, while an explicit stable configuration is recommended for serious deployments.
OAuth resource parameters and scopes
Current Open WebUI versions can automatically discover OAuth resource information and scopes. Leave the Resource Parameter setting on Automatic unless the provider documentation says it must be included or omitted. Likewise, discovered scopes are a sensible starting point; use custom scopes when you deliberately need a narrower or different set.
A successful OAuth discovery check is not a complete MCP health check. It confirms that the authorization metadata was found and parsed; it does not prove that a real tool call will work.
Verify the connection
Do not stop when the connection is merely saved. Start a fresh chat, enable the MCP integration, and ask for a small read-only operation. A deterministic test is better than asking the model to perform a complicated multi-step task immediately.
- Confirm the server URL is correct.
- Confirm the authentication mode matches the server.
- Confirm the server initializes.
- Open a fresh chat.
- Enable the MCP tool.
- Ask for a small read-only result.
- Inspect the returned tool result as well as the final answer.
If a simple tool works, add complexity one step at a time. This makes it much easier to distinguish transport problems from model tool-use problems.
Common error: Failed to connect to MCP server
This message is broad. First check the endpoint and authentication. Then check whether the server actually supports the transport you selected. For OAuth, separate discovery problems from authorization problems and from actual MCP tool execution.
Open WebUI also documents an MCP initialization timeout. A server that takes a long time to start or exposes many tools may need a higher timeout than the default. Raising a timeout is useful only when the server is reachable but genuinely slow.
MCP_INITIALIZE_TIMEOUT=30
Common error: infinite loading after adding the server
Check the connection type first. MCP configuration belongs in the MCP Streamable HTTP connection, not an OpenAPI connection. Disable the problematic connection, refresh the page, and recreate it using the correct type.