mcpo Documentation

To develop or test mcpo locally:

1. Clone and Install:

   git clone https://github.com/open-webui/mcpo.git
   cd mcpo
   uv sync --dev

2. Run Tests:

   uv run pytest

3. Run with Local Changes: To run mcpo using your local modified code from a specific branch:

   git checkout <your-branch>
   uv run mcpo --port 8000 -- <your_mcp_server_command>

uv run mcpo --port 8000 -- uvx mcp-server-time --local-timezone=America/New_York

MCPO supports two ways to complete the OAuth authorization process:

1. Automatic Browser Flow (Default): Set use_loopback: true. MCPO opens your default browser to the authorization page. After authorization, you are redirected to http://localhost:PORT/callback, and MCPO's built-in server captures the code.
2. Manual Copy/Paste Flow: Set use_loopback: false. MCPO prints the authorization URL. You must manually open the URL, authorize, and then copy the full callback URL (including query parameters) back into the MCPO prompt.

For most modern OAuth 2.1 servers, MCPO uses dynamic client registration. You only need to provide the server_url (the base URL of the OAuth server, excluding the /mcp endpoint). MCPO will automatically discover endpoints via /.well-known/oauth-authorization-server and handle registration, authorization, and token refresh.

Supported server type: streamable-http.

{
  "mcpServers": {
    "my-oauth-server": {
      "type": "streamable-http",
      "url": "http://localhost:8000/mcp",
      "oauth": {
        "server_url": "http://localhost:8000"
      }
    }
  }
}

mcpo can proxy MCP servers that communicate via SSE or Streamable HTTP instead of standard stdio.

SSE-compatible MCP server: Use --server-type "sse" and provide the endpoint. You can also pass custom headers using --header.

mcpo --port 8000 --api-key "top-secret" --server-type "sse" -- http://127.0.0.1:8001/sse

Streamable HTTP-compatible MCP server: Use --server-type "streamable-http" and provide the endpoint.

mcpo --port 8000 --api-key "top-secret" --server-type "streamable-http" -- http://127.0.0.1:8002/mcp

If your OAuth server does not support dynamic client registration, you must provide client_metadata manually. This allows you to specify the client name, redirect URIs, and grant types required for the connection.

Note: Do NOT manually set scope, authorization_endpoint, or token_endpoint; these are discovered automatically from the server's metadata.

{
  "mcpServers": {
    "legacy-oauth-server": {
      "type": "streamable-http",
      "url": "http://localhost:8000/mcp", 
      "oauth": {
        "server_url": "http://localhost:8000",
        "storage_type": "file",
        "client_metadata": {
          "client_name": "My MCPO Client",
          "redirect_uris": ["http://localhost:3030/callback"],
          "grant_types": ["authorization_code", "refresh_token"],
          "response_types": ["code"]
        }
      }
    }
  }
}

mcpo can be installed and run using uvx (recommended), pip, or Docker. It acts as a proxy that converts MCP server commands into OpenAPI-compatible HTTP servers.

Using uv (Recommended):

uvx mcpo --port 8000 --api-key "top-secret" -- your_mcp_server_command

Using pip:

pip install mcpo
mcpo --port 8000 --api-key "top-secret" -- your_mcp_server_command

Using Docker:

docker run -p 8000:8000 ghcr.io/open-webui/mcpo:main --api-key "top-secret" -- your_mcp_server_command

To serve mcpo behind a reverse proxy or under a specific URL prefix (e.g., /api/mcpo), use the --root-path argument. All routes will be prefixed with this path.

Example:

mcpo --port 8000 --root-path "/api/mcpo" --api-key "top-secret" -- your_mcp_server_command

Routes will be accessible at http://localhost:8000/api/mcpo/<tool_name>.

The create_oauth_provider function supports two modes of handling the OAuth callback:

• Loopback Mode (use_loopback=True): Starts a local CallbackServer on the specified callback_port. It automatically opens the user's browser to the authorization URL and waits for the redirect to http://localhost:{port}/callback.
• Manual Mode (use_loopback=False): Prints the authorization URL to the console and prompts the user to paste the full callback URL once they have authorized the application.

Common issues and solutions:

• "OAuth server_url required": Ensure server_url is present in the oauth section of your config.
• Browser doesn't open: Verify use_loopback is true and a default browser is configured on your system.
• "No authorization code found": If using manual flow, ensure you copy the complete callback URL including all query parameters.
• Port already in use: Change the callback_port to a different number.
• Tokens not persisting: Verify storage_type is set to "file" and MCPO has write permissions to ~/.mcpo/tokens/.

You can provide environment variables to the proxied MCP server using two methods:

1. Inline via --env: Pass multiple KEY=VALUE pairs.
2. Via a file using --env-path: Specify a path to a .env file. The CLI will load these variables using load_dotenv and merge them into the environment.

Note: If log_level is provided via CLI, it is also injected into the environment as LOG_LEVEL.