Open WebUI now ships with native support for the Model Context Protocol (MCP), which means you no longer need extra bridges just to link your AI chat interface to powerful external tools. This guide walks through a complete Open WebUI MCP setup.

Before native support existed, every Open WebUI MCP setup had to go through mcpo, a proxy that turns MCP tools into regular REST APIs. Today, Open WebUI can connect straight to remote MCP servers over Streamable HTTP, which simplifies the whole Open WebUI MCP setup for cloud-hosted tools.

If you have not installed Open WebUI yet, follow this guide on installing Open WebUI with Ollama before starting this tutorial.

Native MCP vs MCPO: When to Use Each

Not every tool server supports the same transport, so picking the right path is a key part of any Open WebUI MCP setup. Native MCP in Open WebUI only supports Streamable HTTP, because the app is a multi-tenant web platform and cannot safely keep long-lived stdio or SSE connections open across many users.

If your tool only runs as a local stdio process, you need MCPO to wrap it in an OpenAPI layer first.

Factor	Native MCP (Streamable HTTP)	MCPO (stdio/SSE bridge, OpenAPI)
Transport	Streamable HTTP only	stdio, SSE, or HTTP wrapped as OpenAPI
Best for	Remote, cloud-hosted MCP servers	Local tools, CLI-based MCP servers
Auth options	None, Bearer, OAuth 2.1, OAuth 2.1 Static	API key via mcpo --api-key flag
Stability	Experimental, spec changes often (per Open WebUI’s own warning)	Maintained directly by the Open WebUI team, more reliable
Who can add it	Admins only	Admins or users with Direct Tool Servers permission

Open WebUI itself shows a warning inside the Add Connection dialog stating that MCP support is experimental and its spec changes often, which can cause incompatibilities, while OpenAPI support is directly maintained by the Open WebUI team and is the more reliable option.

Keep this in mind for your Open WebUI MCP setup: pick OpenAPI/mcpo whenever the provider offers both options, and use native MCP only when the provider is MCP-only.

Prerequisites for Open WebUI MCP Setup

Before doing any Open WebUI MCP setup, confirm you are running Open WebUI version 0.6.31 or newer, since native MCP support does not exist in older builds.

Confirm your tools are ready on the server:

docker --version
docker compose version
openssl version

Every file in this Open WebUI MCP setup lives inside one clean project folder, so create it now on your host:

mkdir -p ~/openwebui-mcp
cd ~/openwebui-mcp

Note: If you have already installed Open WebUI before starting this Open WebUI MCP setup, running docker compose up -d from a fresh Compose file can fail with a name conflict like this:

Error response from daemon: Conflict. The container name "/open-webui" is already in use by container "..."

Check what already exists:

docker ps -a --filter "name=open-webui"

If it’s safe to bring that same container under Compose management, stop and remove it so Compose can recreate it cleanly:

docker stop open-webui
docker rm open-webui

If you’d rather keep it as a backup instead of deleting it, rename it instead:

docker rename open-webui open-webui-old

Step 1. Generate and Store the Secret Key

This step is the most skipped part of any Open WebUI MCP setup, yet it causes the most painful bugs later. If you connect tools with OAuth or bearer tokens and never set a fixed WEBUI_SECRET_KEY, Open WebUI generates a random one on every restart, and stored credentials break with an “Error decrypting tokens” message.

Generate a strong random key inside ~/openwebui-mcp:

openssl rand -hex 32

Copy the output, then create a .env file:

nano .env

Paste this content, replacing the value with your generated key:

WEBUI_SECRET_KEY=paste-your-generated-key-here
OPEN_WEBUI_PORT=3000

Save and close the file.

Step 2. Create the Open WebUI Docker Compose File

From the ~/openwebui-mcp directory, create the main Compose file:

nano docker-compose.yml

Paste in the full configuration, using the same volume name you found from the prerequisites section if you’re migrating an existing install:

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: open-webui
    restart: unless-stopped
    ports:
      - "${OPEN_WEBUI_PORT:-3000}:8080"
    environment:
      - WEBUI_SECRET_KEY=${WEBUI_SECRET_KEY}
    extra_hosts:
      - "host.docker.internal:host-gateway"
    volumes:
      - open-webui-data:/app/backend/data

volumes:
  open-webui-data:

Once you are done, start the stack:

docker compose up -d
docker compose ps
docker compose exec open-webui env | grep WEBUI_SECRET_KEY

Once this key is fixed, every future step in this Open WebUI MCP setup will survive container restarts without breaking authenticated tool connections.

Open your browser and go to http://your-server-ip:3000 and log in as admin.

Step 3. Locate and Configure the MCP Connection

From your Open WebUI dashboard, go to the Admin Panel > Settings > Integrations > External Tool Servers.

Click the + button in that Connections area to open the Add Connection dialog.

By default, the Type field at the top of the dialog is set to OpenAPI, which is the wrong setting for a native MCP endpoint. Click directly on the word “OpenAPI” to change it to MCP (Streamable HTTP).

Once switched, you will see a yellow warning box confirming MCP support is experimental; this is normal and does not block you from continuing. Fill in the fields as follows:

• Name: a friendly label shown to users, for example. My Remote Tool.
• ID: leave on auto, or set a short slug like mytool.
• Description: optional, a short note on what the tool does.
• URL / API Base URL: the full endpoint of your remote MCP server, for example, https://your-mcp-server.com/mcp.
• Auth: choose Bearer, None, OAuth 2.1, or OAuth 2.1 (Static) depending on what the server requires.

Step 4. Configure Authentication Correctly

Choosing the right auth mode is critical to a secure Open WebUI MCP setup, since a misconfigured header can silently break every tool call.

For a bearer-token server, keep Auth set to Bearer and paste your token into the API Key field next to it; leaving that key empty while Bearer is selected sends a broken empty header, and the server will reject the connection immediately.

For OAuth-based servers, use this flow inside the same dialog:

• Change Auth to OAuth 2.1 or OAuth 2.1 (Static).
• If using Static, enter your Client ID and Client Secret from your identity provider.
• Click Register Client.
• Click Save.
• Open a new chat, click + → Integrations → Tools, and enable the tool to trigger the browser consent screen.

Never set an OAuth 2.1 tool as a default, pre-enabled tool on a model, since OAuth needs an interactive browser redirect that cannot happen mid-request. Let users toggle OAuth tools on manually inside the chat instead.

Step 5. Set Access Control and Function Filtering

Click Access in the top-right of the Add Connection dialog to scope this tool to specific users or groups instead of exposing it to everyone, which keeps this Open WebUI MCP setup secure by default. Regular users cannot add MCP connections themselves; only admins can, though admins can then share access selectively through this same Access control.

Leave the Function Name Filter List field empty to expose every function from the server, or list specific names like func1, !func2 to restrict what the model can call. If leaving it empty causes a connection error, just add a comma as a workaround. It’s a known bug in the current version.

Expand Advanced if you need to set custom timeouts or headers, then click Save at the bottom right to finalize this step of your Open WebUI MCP setup.

Step 6. Enable Native Function Calling on the Model

Saving the connection is not the final step. Go to Admin Settings > Models, edit the model you plan to use with tools, open Advanced Params, and set Function Calling to Native.

Skipping this step is a common reason an otherwise correct Open WebUI MCP setup appears connected but never actually triggers any tool calls in chat.

Step 7. Verify and Test in a Chat

Back in Connections, confirm the new entry shows as connected; if not, check the container logs:

docker compose logs -f open-webui

If your MCP server runs on the same host machine as Open WebUI, use http://host.docker.internal:port instead of localhost, since the container cannot reach the host network.

Open a new chat, click the + icon, then go to Integrations > Tools, and turn your server on. Ask a question that should use the tool, then check if a tool icon shows up in the chat box, click it to see which server responded.

Connecting Local Stdio Tools via MCPO

Many popular MCP servers still only support stdio, meaning they run as local command-line processes rather than remote HTTP services. Since native Open WebUI MCP support is Streamable HTTP only, these tools need MCPO, the same proxy that the Open WebUI team maintains and recommends as the more reliable path.

Create a subfolder and test manually first:

mkdir -p ~/openwebui-mcp/mcpo
cd ~/openwebui-mcp/mcpo
pip install uv
uvx mcpo --port 8000 --api-key "top-secret" -- uvx mcp-server-time --local-timezone=Asia/Dubai

Stop it with Ctrl+C once confirmed working at http://localhost:8000/docs, then containerize it:

nano docker-compose.mcpo.yml

services:
  mcpo:
    image: ghcr.io/open-webui/mcpo:main
    container_name: mcpo
    restart: unless-stopped
    ports:
      - "8000:8000"
    command:
      - --host
      - 0.0.0.0
      - --port
      - "8000"
      - --api-key
      - top-secret
      - --
      - uvx
      - mcp-server-time
      - --local-timezone=Asia/Dubai

docker compose -f docker-compose.mcpo.yml up -d
docker compose -f docker-compose.mcpo.yml ps
curl http://localhost:8000/docs

Back in the Add Connection dialog, set Type to OpenAPI this time (not MCP), and enter http://host.docker.internal:8000 as the URL with your API key set to top-secret. This is the recommended path for legacy stdio tools in a production Open WebUI MCP setup, since it uses the more stable OpenAPI connector.

Hardening Your Open WebUI MCP Setup for Production

Running this at scale demands more care than a local test.

• Always keep a persistent WEBUI_SECRET_KEY in .env and back it up securely.
• Put MCPO and MCP servers behind HTTPS using Nginx or Caddy; never expose them over plain HTTP publicly.
• Prefer OpenAPI/mcpo over native MCP whenever a provider supports both, per Open WebUI’s own stability warning.
• Rotate the --api-key on MCPO periodically.
• Scope every connection with Access Control so only the right teams can use sensitive tools.
• Monitor logs with docker compose logs -f mcpo and alert on repeated auth failures.
• Update regularly: docker compose pull && docker compose up -d

For teams running this in the cloud, hosting Open WebUI and your private MCP or MCPO servers on reliable AI Hosting gives you GPU-backed or isolated VPS nodes built for exactly this kind of workload.

Conclusion

Completing an Open WebUI MCP setup gives your AI assistant real access to external tools, whether they live on a remote HTTPS server through native MCP or run locally through the more stable MCPO/OpenAPI bridge.

We hope you enjoy this guide. For deeper information, you can check the Official Open WebUI MCP Support Page.

FAQs