mcpo (MCP-to-OpenAPI Proxy)
Author: open-webui
Description: mcpo is a simple, secure proxy that exposes any Model Context Protocol (MCP) server/tool as an OpenAPI-compatible HTTP server. It runs an MCP server command (typically stdio-based) or connects to MCP servers over SSE / Streamable HTTP, and publishes REST endpoints plus auto-generated interactive docs (Swagger UI). Key capabilities include: per-tool routing (e.g., /memory, /time), OpenAPI schema generation, API-key protection, serving behind a reverse-proxy subpath via --root-path, multi-server config (Claude Desktop config format) with optional hot reload, and OAuth 2.1 support (dynamic client registration, token storage under ~/.mcpo/tokens/).
Stars: 4.0k
Forks: 446
License: MIT License
Category: Open Source
Overview
Installation
uvx mcpo --port 8000 --api-key "top-secret" -- your_mcp_server_commandpip install mcpo
mcpo --port 8000 --api-key "top-secret" -- your_mcp_server_commanddocker run -p 8000:8000 ghcr.io/open-webui/mcpo:main --api-key "top-secret" -- your_mcp_server_commandgit clone https://github.com/open-webui/mcpo.git
cd mcpo
uv sync --devuv run pytestuv run mcpo --port 8000 -- your_mcp_server_commandmcpo --config /path/to/config.jsonmcpo --config /path/to/config.json --hot-reloadconvert_time
Convert a time between time zones (example tool from the configured MCP server; shown as a tool that can be disabled via `disabledTools`).
FAQs
How do I configure mcpo to run multiple MCP servers behind a single endpoint in Kubernetes with proper ingress routing?
Create a Claude Desktop-format config JSON defining each MCP server under mcpServers, mount it into your pod, then start mcpo with --config pointing to that file. In your ingress, route to the mcpo service using path-based rules. Set --root-path to match your ingress prefix if mcpo sits behind a subpath, ensuring OpenAPI generation aligns with exposed URLs.
Why are my MCP tools not being invoked when I register mcpo's root URL in Open WebUI instead of individual server subpaths?
The root URL does not aggregate tools across multiple MCP servers in mcpo's architecture. Each server is isolated at its own subpath, and Open WebUI requires the full subpath URL to route requests to the specific server process. Without the subpath, Open WebUI cannot match tool calls to the correct backend, causing silent invocation failures.
Which MCP servers are fully compatible with mcpo and which ones have reduced functionality due to the lack of MCP Resources support?
Tool-focused servers like mcp-server-time, mcp-server-fetch, and server-brave-search work fully with mcpo. Servers depending on MCP Resources protocol, such as filesystem and sequential-thinking servers, experience reduced functionality. This limitation stems from mcpo's current inability to proxy the Resources API, affecting any server that exposes file-like content or structured data beyond simple tool calls.
Can I use mcpo's --strict-auth flag together with --api-key to secure both the Swagger UI docs endpoint and the REST API endpoints?
Yes. The strict-auth flag extends API key protection from REST endpoints to the Swagger UI docs at /docs. Without it, docs remain publicly accessible even when api-key is set. This combination ensures both endpoints and interactive documentation require authentication, crucial when mcpo sits behind public ingress or shared reverse proxies.
What are the limitations of mcpo's OAuth 2.1 support and how do I handle token refresh issues with long-lived sessions?
mcpo's OAuth 2.1 implementation has documented issues with token URL parameter handling and refresh behavior affecting long-lived sessions. Test your provider's token refresh flow before production, monitor token expiration in logs, and implement application-level session management that handles re-authentication gracefully when automatic refresh fails. Maintain fallback authentication paths for critical workflows.
How does mcpo compare to Microsoft's mcp-gateway for enterprise Kubernetes deployments at scale?
Microsoft's mcp-gateway provides control plane and data plane separation optimized for enterprise Kubernetes lifecycle management, making it better suited for teams with existing Kubernetes operations who need pod-level orchestration, health checks, and autoscaling policies. mcpo prioritizes developer velocity through zero-config Swagger UI, hot reload, and Claude Desktop config reuse, fitting teams needing fast HTTP exposure without deep orchestration requirements.