centersl/open-webui-docs
1
0
Fork 0
mirror of https://github.com/open-webui/docs.git synced 2026-03-27 13:28:37 +07:00
Code Issues Packages Projects Releases Wiki Activity

docs: OAuth 2.1 MCP tools cannot be default tools (known limitation)

Browse Source 
- Add warning to MCP auth section explaining the interactive browser
  redirect requirement that prevents OAuth 2.1 tools from working
  as default/pre-enabled tools on models
- Add troubleshooting entry for 'Failed to connect to MCP server'
  when caused by OAuth 2.1 default tool misconfiguration
- Document workaround: manually enable per-chat via + button
This commit is contained in:
Classic
2026-03-01 11:39:21 +01:00
parent 9a55aa33be
commit 0232e9216e
1 changed files with 9 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs/features/extensibility/mcp.mdx
View File

@@ -64,6 +64,14 @@ Browser-based, multi-user deployments increase the surface area (CORS/CSRF, per-
* **Bearer**: Use this **only** if your MCP server requires a specific API token. You **must** populate the "Key" field. * **Bearer**: Use this **only** if your MCP server requires a specific API token. You **must** populate the "Key" field.
* **OAuth 2.1**: For secured, enterprise deployments requiring Identity Provider flows. * **OAuth 2.1**: For secured, enterprise deployments requiring Identity Provider flows.
:::warning OAuth 2.1 Tools Cannot Be Set as Default Tools
**Do not set OAuth 2.1 MCP tools as default/pre-enabled tools on a model.** The OAuth 2.1 authorization flow requires an interactive browser redirect (user consent, callback) that cannot happen transparently during a chat completion request.
If an OAuth 2.1 tool is set as a default and the user hasn't previously authenticated (or their refresh token has expired), the tool call will fail with **"Failed to connect to MCP server"** because the backend cannot initiate the browser-based auth flow mid-request.
**Workaround:** Users should manually enable OAuth 2.1 tools per-chat via the **➕** button in the chat input area. This triggers the auth flow before the tool is ever invoked. Token refresh works automatically once the initial authentication is complete.
:::
### Connection URLs ### Connection URLs
If you are running Open WebUI in **Docker** and your MCP server is on the **host machine**: If you are running Open WebUI in **Docker** and your MCP server is on the **host machine**:
@@ -85,6 +93,7 @@ The chat shows "Failed to connect to MCP server" when using a tool, even if the
**Solutions**: **Solutions**:
1. **Check Authentication**: Ensure you haven't selected `Bearer` without a key. Switch to `None` if no token is needed. 1. **Check Authentication**: Ensure you haven't selected `Bearer` without a key. Switch to `None` if no token is needed.
2. **Filter List Bug**: If the "Function Name Filter List" is empty, try adding a comma (`,`) to it. 2. **Filter List Bug**: If the "Function Name Filter List" is empty, try adding a comma (`,`) to it.
3. **OAuth 2.1 Default Tool**: If the failing tool uses OAuth 2.1 and is set as a default tool on the model, this is a [known limitation](#oauth-21-tools-cannot-be-set-as-default-tools). Remove it from the model's default tools and have users enable it manually per-chat.
### Infinite loading screen after adding External Tool ### Infinite loading screen after adding External Tool