Open WebUI MCP Server Integration: A Complete Setup Guide

Every MCP integration with Open WebUI starts at the same fork in the road: can the two talk directly, or do they need a translator standing between them? The answer hinges on one detail: the connection type your server speaks.

• Streamable HTTP servers: Open WebUI can use MCP tools natively (v0.6.31 and later). Go to Settings > Admin > Integrations > Add Connection, and set Type to MCP (Streamable HTTP).
• stdio or SSE servers: Open WebUI can’t call these directly. You’ll need the mcpo proxy to expose the server’s tools as OpenAPI endpoints it can register and call.

Here’s the catch: most MCP servers speak stdio or SSE, not Streamable HTTP. So native support, convenient as it is, won’t help with the server you’re probably trying to connect.

That’s where mcpo (Model Context Protocol OpenAPI) comes in. It’s a proxy that sits between the two: your MCP server speaking one language, Open WebUI speaking another, and mcpo translating in between.

This guide walks through that translation end to end: getting mcpo running, registering it in Open WebUI, and fixing the connection errors that tend to show up along the way.

What is mcpo and how does it connect MCP servers to Open WebUI?

Model Context Protocol (MCP) lets large language models use external tools and APIs. It’s the open webui model context protocol layer that makes tool calling possible in the first place.

Open WebUI’s native support only covers one connection type. If your MCP server uses Streamable HTTP, Open WebUI connects to it directly. You’ll find this under Settings > Admin > Integrations > Add Connection, with Type set to MCP (Streamable HTTP).

Most MCP servers don’t use Streamable HTTP, though. Many use standard input/output (stdio) or SSE instead. Open WebUI can’t call these directly. This is where mcpo, the MCP-to-OpenAPI proxy, comes in.

How does mcpo connect MCP servers to Open WebUI?

mcpo runs your MCP server as a background process. It then exposes that server’s tools as OpenAPI HTTP endpoints. Open WebUI can inspect these endpoints and call them like any other tool server.

This is the core of mcpo open webui integration: mcpo acts as the translator, so Open WebUI never has to speak stdio or SSE directly. It just calls a standard OpenAPI endpoint.

mcpo isn’t limited to stdio and SSE servers, either. With the --server-type flag, it can also front SSE and Streamable HTTP servers, so you can run one proxy pattern across different server types if needed.

On paper, that’s a lot of flexibility for one small proxy. In practice, it comes down to three steps: launching mcpo, pointing it at your MCP server, and linking it to Open WebUI so the two can actually find each other.

How do you set up an MCP tool server with mcpo?

You can run mcpo as a Python package or a Docker container. This guide uses Docker, since it’s the simplest way to run mcpo with Open WebUI as two linked containers.

Step 1: Launch the mcpo container

Use the official ghcr.io/open-webui/mcpo:main image. mcpo launches your MCP server command and exposes its tools as an OpenAPI HTTP service.

Step 2: Pass the host, port, API key, and MCP server command

mcpo takes its settings as command-line arguments, not environment variables. This is the core of mcpo’s open webui mcp server configuration:

• Set --host 0.0.0.0 and --port 8000
• Add an --api-key
• Put your MCP server command after --

To run several MCP servers from one mcpo instance, pass a JSON file with --config instead.

Step 3: Link containers with Docker Compose

Define both services in a single docker-compose.yml file. Compose puts them on a shared network, so Open WebUI can resolve mcpo by its service name. This is how to run an MCP server with Open WebUI in Docker without managing two separate networks by hand.

Create the file with both services defined:

services:
  mcpo:
    image: ghcr.io/open-webui/mcpo:main
    command: ["--host", "0.0.0.0", "--port", "8000", "--api-key", "your-mcpo-api-key", "--", "uvx", "mcp-server-time", "--local-timezone=America/New_York"]
    restart: unless-stopped

  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    environment:
      - WEBUI_SECRET_KEY=your-secret-key
    volumes:
      - open-webui:/app/backend/data
    restart: unless-stopped

volumes:
  open-webui:

This example runs the mcp-server-time server from the mcpo README. Replace everything after -- with your own MCP server command.

A couple of details matter here:

• mcpo has no ports: entry. Published ports bypass ufw, so keep this service unpublished and let Open WebUI reach it over the internal Compose network.
• Replace your-secret-key with the output of openssl rand -hex 32. This keeps users logged in across container updates.

Once both containers are running, the next step is connecting mcpo to Open WebUI as a registered tool server.

How do you add the MCP server to Open WebUI’s admin panel?

Registering mcpo takes no custom code. If Open WebUI isn’t running yet, follow our guide on how to install Open WebUI. If Open WebUI already runs in its own container, skip the open-webui service from the Compose file above. Just attach your existing container to the same Docker network as mcpo, so it can resolve mcpo by name.

Here’s how to add mcp server to open webui once both containers are on the same network:

Step 1: Open the global tool server settings

Log in to Open WebUI as an administrator. Go to Settings > Admin > Integrations, and find the Tools section.

Open WebUI mcp server support works at two levels here:

• Global tool servers are called from the Open WebUI server itself. Docker container names, like mcpo, resolve correctly here.
• Per-user tool servers are called from the browser instead. Container names don’t resolve there, since the browser isn’t on the Docker network.

For mcpo, use a global tool server.

Step 2: Enter the mcpo server URL

Add a connection and set its Type to OpenAPI. Enter the base URL http://mcpo:8000, not the /openapi.json path.

If you’re running mcpo with a config file to serve multiple MCP servers, add each one separately, using its own subpath. For example: http://mcpo:8000/time.

Enter the key you passed to --api-key in the connection’s authentication field, then save.

A common cause of open webui failed to connect to mcp server errors: entering mcpo’s root URL instead of a tool’s specific subpath. Open WebUI needs the full subpath to route tool calls to the right backend. Without it, tool calls fail silently instead of returning a clear error.

Step 3: Enable the tool in a chat

Global tools are off by default in every chat. To connect mcp server to open webui tools inside a conversation:

1. Click the Integrations button in the message input.
2. Open Tools.
3. Switch on your mcpo tool.
4. Send a prompt that needs it, using a model that supports tool calling.

At this point, mcpo and Open WebUI can talk. The question is whether they’ll still be able to tomorrow.

Why choose Bluehost VPS hosting for Open WebUI and MCP tools? 

Everything in the setup above assumes a machine that’s always there. Look back at the Compose file: restart: unless-stopped brings mcpo back if the container crashes, but it does nothing if the machine underneath sleeps, reboots, or gets closed, which is exactly what a laptop does. The ufw detail from Step 3 carries the same hidden assumption: not publishing port 8000 only matters if you’re already running this on a Linux server, something this guide never actually confirmed you have.

That gap, a container configuration that only works on hardware built to stay on, is exactly what self-managed VPS hosting with Docker support closes. At Bluehost, our Self-Managed NVMe 4 plan is built for this kind of workload: 2 vCPUs, 4 GB DDR5 RAM, and 100 GB NVMe storage, enough headroom to run mcpo and Open WebUI as persistent, resolvable services instead of processes that happen to be running right now.

What the NVMe 4 plan actually fixes

• A machine that doesn’t sleep: Your laptop closing or your workstation rebooting no longer takes mcpo down with it. restart: unless-stopped finally has hardware worth promising that to.
• A server, not a guess: The ufw assumption this guide made earlier stops being an assumption. NVMe 4 gives you the Linux environment that detail was quietly depending on.
• Headroom for more than one proxy: 4 GB of DDR5 RAM and 100 GB of NVMe storage mean mcpo and Open WebUI aren’t competing for resources with each other, or with whatever else you run alongside them.

The trade-off: you still manage Linux and Docker networking yourself, how VPS hosting works puts that responsibility on you, not on the platform. What it buys you is simpler but more fundamental: a machine that’s actually there when Open WebUI tries to reach mcpo.

From proxy to production: What your MCP setup actually needs

Open WebUI connects Streamable HTTP MCP servers natively. For everything else, mcpo steps in as the translator, turning stdio and SSE servers into OpenAPI tools that Open WebUI can register and call. Between the two paths, that’s the real question this guide set out to answer: how to get an MCP server talking to Open WebUI, whatever transport it speaks.

But talking to each other once isn’t the same as staying connected. mcpo and Open WebUI resolving each other by name solves the “can they talk” problem. Whether that connection is still there tomorrow is a different problem entirely, and it depends on what’s running underneath both containers.

Build on Bluehost VPS hosting and that question stops being one you have to think about.

FAQs