Use MetaMCP to manage tools for Open WebUI

Jincheng (James) Zhang — Wed, 30 Jul 2025 11:17:21 +0000

To clone and self-host MetaMCP checkout: https://github.com/metatool-ai/metamcp
(MCP Aggregator, Orchestrator, Middleware, Gateway in one docker)

There is also a doc version of this post: https://docs.metamcp.com/en/integrations/open-web-ui

This guide will show you how to use MetaMCP to host MCPO like openapi.json endpoints of your managed MCPs so you can integrate it as tools in Open WebUI.

🎯 What You'll Learn

How to deploy and configure MetaMCP
Setting up MCP servers and namespaces
Creating OpenAPI endpoints for Open WebUI
Configuring authentication and API keys
Troubleshooting common issues

📋 Prerequisites

Before starting, ensure you have:

Docker and Docker Compose installed
Open WebUI running (locally or deployed)
MetaMCP deployed with a properly configured APP_URL (default: http://localhost:12008)

🚀 Step 1: Deploy MetaMCP with Proper Configuration

Clone and Setup MetaMCP

If you haven't already, clone MetaMCP and set it up:

git clone https://github.com/metatool-ai/metamcp.git
cd metamcp
cp example.env .env

Configure APP_URL for Open WebUI Access

Critical: Configure your APP_URL properly in the .env file for Open WebUI integration:

# For local Open WebUI accessing local MetaMCP
APP_URL=http://localhost:12008

# For deployed Open WebUI accessing deployed MetaMCP
APP_URL=https://your-metamcp-domain.com

# For local Open WebUI accessing deployed MetaMCP
APP_URL=https://your-metamcp-domain.com

⚠️ Important: Open WebUI must be able to reach your MetaMCP instance at the configured APP_URL. Ensure firewall rules and network configuration allow this access.

Also configure other production settings:

POSTGRES_PASSWORD=your_secure_password
BETTER_AUTH_SECRET=your_auth_secret  # Generate with: openssl rand -hex 32 | base64

Start MetaMCP

Launch MetaMCP using Docker Compose:

docker compose up -d

Verify it's running by visiting your configured APP_URL.

🔧 Step 2: Configure MetaMCP for Open WebUI

Create MetaMCP Account

Open your browser and go to your APP_URL (e.g., http://localhost:12008)
Create an account or log in
(Recommended) Disable new user registration in Settings for security

Add MCP Servers

Add the MCP servers you want to expose to Open WebUI:

Navigate to MCP Servers in the sidebar
Click "Add Server" button
Configure your server (example with filesystem server):

Basic Information:

Name: hacker-news-server
Description: Hacker News integration for fetching stories and comments
Type: STDIO

Server Configuration:

Command: uvx
Arguments: mcp-hn
Environment Variables: (if needed)

Ownership:

Choose "Everyone (Public)" for Open WebUI access

Click "Create Server"

💡 Tip: Repeat this process for all MCP servers you want to make available to Open WebUI.

Create a Namespace

Group your MCP servers into a namespace for Open WebUI:

Go to Namespaces in the sidebar
Click "Create Namespace"
Configure the namespace:

Basic Information:

Name: openwebui-tools
Description: Aggregated tools for Open WebUI integration

Ownership:

Choose "Everyone (Public)"

Select MCP Servers:

Check all servers you want to include
These will be aggregated into one endpoint

Click "Create Namespace"

Manage Tools (Optional)

Fine-tune which tools are available:

Click on your "openwebui-tools" namespace
Review the Tools Management section
Disable any tools you don't want Open WebUI to access
This helps keep the tool set focused and secure

🔗 Step 3: Create OpenAPI Endpoint

Create Public Endpoint

Create an endpoint that Open WebUI can consume:

Navigate to Endpoints in the sidebar
Click "Create Endpoint"
Configure the endpoint:

Basic Information:

Name: openwebui-api
Description: OpenAPI endpoint for Open WebUI integration

Ownership:

Choose "Everyone (Public)"

Namespace Selection:

Select your "openwebui-tools" namespace

API Key Authentication:

Enable API Key Authentication: Toggle ON
Use Query Parameter Authentication: Toggle OFF (Open WebUI supports Bearer tokens)

MCP Server Creation:

Check "Automatically create an MCP server for this endpoint"

Click "Create Endpoint"

Your OpenAPI endpoint will be available at:

OpenAPI UI: {APP_URL}/metamcp/openwebui-api/api
OpenAPI Schema: {APP_URL}/metamcp/openwebui-api/api/openapi.json

🔑 Step 4: Generate API Key

💡 Tip: In the last step, if you select "Automatically create an MCP server for this endpoint" option, then at least one API key will be automatically generated for you. Feel free to use it instead of creating a new one.

Create API Key for Open WebUI

Go to API Keys in the sidebar
Click "Generate Key"
Configure the API key:

Key Information:

Description: Open WebUI Integration Key
Scope: Public (so Open WebUI can use it)

Click "Generate Key"
Important: Copy the generated key (starts with sk_mt_)

⚠️ Warning: Save this key securely - it's only shown once and will be needed for Open WebUI configuration.

🎨 Step 5: Configure Open WebUI

Step 5.1: Open Web UI

Open your Open Web UI page. Find settings.

Step 5.2: Settings > Tools

In Settings pop up. Go to "Tools".

Step 5.3: Settings > Tools > Add connection

Under "Manage Tool Servers" on top right corner click on the "+" button to add a connection.

For URL > Base URL enter {APP_URL}/metamcp/openwebui-api/api. For example if APP_URL is http://localhost:12008 then enter http://localhost:12008/metamcp/openwebui-api/api.

For URL > openapi.json Path enter {APP_URL}/metamcp/openwebui-api/api/openapi.json. For example if APP_URL is http://localhost:12008 then enter http://localhost:12008/metamcp/openwebui-api/api/openapi.json.

Put the "API Key" generated in previous steps to "Auth Bearer" field.

Use the "refresh" button to test connection.

Step 5.4: Back to chat and verify the listed tools

Close any pop ups. In home page click new chat. Then inspect the available tools.

Step 5.5: Chat with tool calling

In new chat, a query of "show top hacker news" would look like:

💡 Tip: Then in new chats, with a model that supports tool calling, should automatically try to call tools if necessary.

🔧 Troubleshooting

Common Issues

Connection Errors:

Verify APP_URL is accessible from Open WebUI
Check firewall and network configuration
Ensure API key is correctly configured. Turn off Auth to test if it works first.
With Auth off, you can manually visit e.g., http://localhost:12008/metamcp/openwebui-api/api/openapi.json to verify the openapi.json.

Authentication Issues:

Verify API key format (should start with sk_mt_)
Ensure Bearer token authentication is properly configured in Open WebUI
Verify Authorization header format: Bearer {your_api_key}

Tool Execution Failures:

Check MCP server status in MetaMCP dashboard
Review tool permissions in namespace settings
Monitor logs for specific error messages

CORS Errors:

Ensure Open WebUI domain is allowed
Check MetaMCP CORS configuration
Verify APP_URL matches access URL

Need Help?

Check MetaMCP GitHub Issues
Join our Discord community
Review Open WebUI documentation if necessary

🎉 Conclusion

You've successfully integrated MetaMCP with Open WebUI! This setup provides you with:

Centralized tool management through MetaMCP
Enhanced AI capabilities in Open WebUI
Secure API key authentication
Scalable architecture for adding more tools

The integration allows you to leverage the power of various MCP servers while maintaining a clean, organized tool management system. Whether you're using local or deployed instances, this setup provides a robust foundation for AI-powered workflows.

Resources:

Let's rock! 🚀

DEV Community: Jincheng (James) Zhang

Use MetaMCP to manage tools for Open WebUI

🎯 What You'll Learn

📋 Prerequisites

🚀 Step 1: Deploy MetaMCP with Proper Configuration

Clone and Setup MetaMCP

Configure APP_URL for Open WebUI Access

Start MetaMCP

🔧 Step 2: Configure MetaMCP for Open WebUI

Create MetaMCP Account

Add MCP Servers

Create a Namespace

Manage Tools (Optional)

🔗 Step 3: Create OpenAPI Endpoint

Create Public Endpoint

🔑 Step 4: Generate API Key

Create API Key for Open WebUI

🎨 Step 5: Configure Open WebUI

Step 5.1: Open Web UI

Step 5.2: Settings > Tools

Step 5.3: Settings > Tools > Add connection

Step 5.4: Back to chat and verify the listed tools

Step 5.5: Chat with tool calling

🔧 Troubleshooting

Common Issues

Need Help?

🎉 Conclusion