Open WebUI MCP Server: Complete Setup Guide

Open WebUI supports Model Context Protocol (MCP) servers natively, letting your AI models access external tools and data in real time. If you're running Open WebUI v0.6.31 or later, you can connect MCP servers directly through the admin panel or route local servers through a proxy gateway. This guide covers both methods, common setup mistakes, and troubleshooting.

What is MCP (Model Context Protocol)?

MCP is a standardized protocol for connecting AI models to external tools and data sources. Unlike OpenAPI endpoints that are stateless, MCP servers maintain context across multiple tool calls, making them ideal for workflows that require sequential operations or stateful data access.

Think of it this way: OpenAPI is good for single, isolated API calls. MCP is good when your model needs to reason about a series of steps, hold information in memory, and make decisions based on previous results. A filesystem MCP server, for example, can let your model browse a folder, then read a specific file, then modify it--all in one conversation thread.

MCP servers come in two flavors. HTTP/SSE servers expose an HTTP endpoint and use Server-Sent Events for streaming. Stdio servers run as local processes and communicate via standard input/output (usually how you'd run them locally with Node.js, Python, or Bash). Open WebUI's native support handles HTTP/SSE directly. For stdio servers, you need a proxy.

Why use MCP at all? Because it drastically expands what your Open WebUI instance can do without you building custom integrations. Instead of shipping code to add a new capability, you spin up an MCP server and point Open WebUI at it. The ecosystem is already packed with pre-built servers for Slack, GitHub, file access, databases, and more.

Does Open WebUI Support MCP Natively?

Yes. Open WebUI added native MCP support in v0.6.31 (released in late 2024). Check your version in Settings > About. If you're running an earlier version, you need to upgrade.

One crucial limitation: native support covers HTTP and Server-Sent Events transports only. It does not handle stdio servers directly--those local process-based servers need a proxy gateway like MCPO to translate between stdio and HTTP.

Support is admin-only. Regular users cannot add MCP servers; only account administrators (users with the Admin role in Open WebUI) can configure them under Settings > Integrations > External Tool Servers. This is by design for security--you do not want any user spinning up arbitrary external tool connections.

Also, your Open WebUI instance must have WEBUI_SECRET_KEY set in your environment variables. This is your admin authentication token, and MCP connections use it to identify themselves to Open WebUI. If this is missing, MCP server connections will fail silently with cryptic error messages in the logs.

The model matters too. Not all models are MCP-aware. Older or lighter models may not reliably call tools even if they are connected. For best results, use a recent model with 7B+ parameters and explicit tool-use training (Llama 3.1, Claude, Mistral, etc.).

Two Setup Methods: Which Do You Use?

You have two paths depending on where your MCP server lives.

Method 1: Direct Native Connection (HTTP/SSE servers). If your MCP server exposes an HTTP endpoint--either on a public URL or on your local network--connect it directly. This is the simplest path. No proxy, no extra software. Open WebUI talks to the server directly. Use this for commercial MCP services, Anthropic's Claude MCP servers published over HTTP, or any server you've deployed to a server.

Method 2: MCPO Proxy (Stdio servers). If your MCP server runs locally as a command (like npx -y @modelcontextprotocol/server-filesystem or python my-mcp-script.py), it communicates via stdio and does not expose HTTP. You need MCPO--a lightweight Python/Node proxy that wraps stdio servers and exposes them as HTTP endpoints. Open WebUI talks to MCPO, which talks to your stdio server. This adds one layer of indirection but is still fast and simple.

Decision tree: Does your MCP server have a URL? Use Method 1. Does it run as a local command you'd execute in a terminal? Use Method 2 (MCPO).

Method 1: Direct Native Connection (HTTP/SSE Servers)

Start here if your server is HTTP-accessible.

Step 1: Verify your Open WebUI version and SECRET_KEY.

Log in as admin and go to Settings > About. Confirm v0.6.31 or later. Then check that your Docker or environment has WEBUI_SECRET_KEY set. If you started Open WebUI with Docker:

docker run... -e WEBUI_SECRET_KEY=your-secret-here...

If it is missing, add it and restart.

Step 2: Get your MCP server URL.

You need the full HTTP URL to your server. This could be a public domain for a remote server, a private IP address with port for a local network server, or a localhost address if running on the same machine. Note the scheme (http or https) and the port if it is not 80 or 443.

Step 3: Add the server in Open WebUI.

Go to Settings > Admin (or Settings > Integrations > External Tool Servers). Click the plus icon to add a new external tool server. Fill in:

• Name: Something descriptive, like "My File Server" or "GitHub Tools".
• Server URL: The full HTTP URL from step 2.
• Connection Type: Select "HTTP" (not stdio).
• Authentication: Choose based on your server's requirements.
  • None: If the server does not require auth.
  • Bearer Token: If the server expects an Authorization: Bearer <token> header. Paste your token.
  • OAuth 2.1: For servers using OAuth. Provide Client ID, Client Secret, and Token URL.
  • API Key: If the server uses a custom API key header.

Step 4: Test the connection.

Click "Test Connection" or "Save". Open WebUI will attempt to handshake with the server. If it succeeds, the server is now available to all models in your instance. If it fails, check the error message and troubleshoot (see the Troubleshooting section below).

Step 5: Use it in a conversation.

Start a new chat with a capable model. The model will see the MCP server's tools in its context and can call them as needed. You do not need to enable anything per-conversation; if it is added at the admin level, it is available.

Method 2: MCPO Proxy (Local Stdio Servers)

Use this path if your MCP server runs locally as a command.

What is MCPO?

MCPO (MCP-to-OpenAPI) is a lightweight proxy. It wraps a stdio MCP server in an HTTP gateway, so Open WebUI (which only speaks HTTP) can reach it. You run MCPO in the background, then point Open WebUI at MCPO's HTTP endpoint.

Step 1: Install and run MCPO.

The easiest way is Docker. If you have Docker:

docker run -d --name mcpo -p 8000:8000 \
  -e MCP_SERVERS='[{"name": "filesystem", "command": "npx -y @modelcontextprotocol/server-filesystem --allow-read."}]' \
  ghcr.io/open-webui/mcpo:latest

This spins up MCPO and configures it to run the official filesystem MCP server. Replace the MCP_SERVERS JSON with your own server command.

Alternatively, install via pip:

pip install mcpo
mcpo run --mcp-server "npx -y @modelcontextprotocol/server-filesystem --allow-read."

MCPO listens on the default local port 8000 once running.

Step 2: Verify MCPO is running.

Test the health endpoint by making a request to the root of MCPO. You should get a 200 response with status information. You can use curl or any HTTP client to verify that MCPO is responding.

Step 3: Add MCPO to Open WebUI (same as Method 1).

Go to Settings > Admin > Integrations > External Tool Servers. Add a new server:

• Name: "MCPO Proxy" or similar.
• Server URL: The address where MCPO is running (localhost:8000 on the same machine).
• Connection Type: HTTP.
• Authentication: None (unless you added auth to MCPO itself).

Click "Test Connection" to verify.

Step 4: Troubleshoot if MCPO and Open WebUI are on different machines.

If Open WebUI is in Docker and MCPO is on your host, use the appropriate Docker hostname (Docker Desktop and Linux with host.docker.internal enabled support this). If both are Docker containers on the same network, use the container name. If both are on the same host outside Docker, use the localhost address.

Authentication & Security: OAuth 2.1, Bearer Tokens, and Admin Scope

MCP servers often need credentials to access the resources they manage. Open WebUI supports several auth patterns.

Bearer Token (Simplest).

If your server expects an Authorization: Bearer <token> header, select Bearer in the UI and paste your token. Use this for servers with simple API keys or tokens (many open-source MCP servers use this).

OAuth 2.1 (Most Secure for Production).

OAuth 2.1 is the enterprise standard. Your server acts as an OAuth provider. Open WebUI obtains a token on your behalf and renews it automatically. To set up:

1. Register Open WebUI as an OAuth client with your server/provider.
2. Get your Client ID and Client Secret.
3. Note the Token URL (where Open WebUI requests tokens).
4. In the UI, select OAuth 2.1 and fill in these three fields.
5. Click "Connect Account" to authorize. You will be redirected to your server to log in.
6. Open WebUI stores and auto-refreshes the access token.

OAuth is harder to set up but much safer for production--your token is never stored in plaintext, and it can expire and refresh without you managing it manually.

Admin-Only Scope.

Remember: only admins can add or modify MCP server connections. A regular user cannot accidentally connect a server or expose sensitive credentials. This is a hard boundary in Open WebUI's permission model and is intentional for security.

WEBUI_SECRET_KEY.

This environment variable must be set for MCP to work at all. It is your Open WebUI instance's identity. Make sure it is:

• Long and random (at least 32 characters).
• Stored securely (in a secrets manager, not in Git or logs).
• The same across all Open WebUI replicas if you are running multiple instances.

If WEBUI_SECRET_KEY is missing or wrong, MCP handshakes fail silently--Open WebUI will not raise an error in the UI, but the server will log connection failures.

Troubleshooting: Common Errors and Fixes

Error: "Failed to connect to MCP server."

This is the most common error and has several causes:

1. URL is wrong or server is offline. Manually visit the server URL in your browser. If you get a 404 or timeout, the server is not running or the URL is incorrect. Fix the URL or start the server.

2. WEBUI_SECRET_KEY is missing. Check that your Open WebUI container or process has WEBUI_SECRET_KEY in its environment. Restart Open WebUI after adding it.

3. Authentication failed. If the server requires Bearer token or OAuth, verify your credentials are correct. For Bearer tokens, try the URL + header manually with curl using your token to see if the server rejects it.

4. Network unreachable (localhost or internal IP). If your MCP server is on localhost and Open WebUI is in Docker, use the appropriate Docker hostname. If both are Docker containers, use the container name instead of localhost.

5. Slow server handshake. Some MCP servers take a few seconds to initialize their tool list. Open WebUI has a timeout (usually 10-15 seconds). If your server is slow, you may see this error during peak usage. Optimize the server or increase the handshake timeout in Open WebUI's config if the option is available.

Error: "Infinite loading screen after adding an external tool."

This usually means:

1. Wrong connection type selected. Double-check that you chose "HTTP" for HTTP/SSE servers, not "Stdio" (stdio is not supported directly).

2. Server returned an invalid response. The server responded but with malformed JSON or an unexpected format. Check the server logs.

3. Model is not MCP-aware. If you added the server but it is not appearing in model conversations, your model may not support tool use. Try a different model (Llama 3.1, Mistral, Claude equivalents in your setup) and test again.

"Permission denied" or "Unauthorized" errors.

You are not logged in as an admin, or your admin credentials do not have the Integrations scope. Ask your Open WebUI administrator to add the MCP server, or request admin permissions for yourself.

Running MCP at Scale: Next Steps with Managed Open WebUI

Once you have MCP working locally, production deployment raises questions: How do you run this reliably? How do you secure multiple MCP connections? How do you monitor uptime and handle failures?

Opsily manages Open WebUI for teams, handling infrastructure, updates, backups, and scaling. If you integrate MCP servers now, Opsily keeps them running securely across environments without you managing Docker, reverse proxies, or SSL certificates. You add the server once in the admin panel, and it stays available--automatically patched, backed up, and monitored.

Start with Opsily's managed Open WebUI to run MCP in production. No server management. No infrastructure overhead.

Frequently Asked Questions

How do I add an MCP server to Open WebUI?

Log in as admin, go to Settings > Integrations > External Tool Servers, and click the plus icon to add a new server. Provide the server URL, select the connection type (HTTP for remote servers, or HTTP pointing to MCPO for local stdio servers), configure authentication if needed, and test the connection.

Why does Open WebUI say "Failed to connect to MCP server"?

This error has multiple causes: the server URL is incorrect or the server is offline, WEBUI_SECRET_KEY is not set in Open WebUI's environment, authentication credentials (Bearer token or OAuth) are wrong, or the server is on localhost and Open WebUI cannot reach it due to network isolation (common in Docker). Verify each in order: test the URL manually, confirm WEBUI_SECRET_KEY is set, validate credentials, and adjust network settings if needed.

How to connect an MCP server running on my local machine?

If the server is local and Open WebUI is in Docker, use the appropriate Docker hostname. If both are Docker containers, use the container name. If both are on the same host outside Docker, use the localhost address with the appropriate port.

What is MCPO, and when do I need it?

MCPO is a proxy that wraps local stdio MCP servers and exposes them as HTTP endpoints. Use it if your MCP server runs as a command-line process (like node my-server.js) rather than listening on an HTTP port. MCPO translates stdio to HTTP, so Open WebUI can reach it.

Do all models support MCP?

No. Your model needs to understand and call external tools. Newer, larger models (Llama 3.1 7B+, Mistral, Claude) are typically good choices. Older or quantized models may not reliably use MCP tools. Test with your model; if it ignores the tools, try a different one.

What is WEBUI_SECRET_KEY, and how do I set it?

WEBUI_SECRET_KEY is Open WebUI's internal authentication token. MCP connections use it to verify they are talking to the right instance. Set it in your Docker environment (-e WEBUI_SECRET_KEY=your-secret-here) or in your docker-compose.yml env file. It must be a long random string (32+ characters) and must be the same across all instances if you are running multiple replicas.

Can regular users add MCP servers?

No. Only administrators can add, remove, or modify MCP server connections. This is a security boundary in Open WebUI; regular users cannot spin up arbitrary external tool access.

The Bottom Line

MCP is a powerful way to extend Open WebUI without custom code. Open WebUI supports it natively since v0.6.31, and setup is straightforward: connect HTTP servers directly or use MCPO to proxy local stdio servers. Authentication and WEBUI_SECRET_KEY are prerequisites. Troubleshooting is usually about verifying the URL, checking credentials, and confirming network access.

Once you have MCP running, you have models that can call external tools reliably and maintain context across multiple operations. For production, let Opsily manage the infrastructure so you focus on your MCP servers and workflows. Start with Opsily's managed Open WebUI today.