MCP Servers

Integrate Model Context Protocol servers with Open WebUI

Model Context Protocol (MCP) is an open standard that enables AI models to securely access external data sources and tools. Open WebUI supports MCP servers, allowing you to connect your models to databases, APIs, file systems, and other services.

Overview

MCP provides:

• Standardized protocol for AI-to-service communication
• Secure authentication and authorization
• Dynamic tool discovery
• Resource access (files, databases, APIs)
• OAuth 2.1 support for user-specific credentials

MCP is installed as part of Open WebUI. The mcp Python package (version 1.26.0) is included in the requirements.

What is MCP?

MCP (Model Context Protocol) is a standardized way for AI models to interact with external systems. It provides:

• Tools: Functions that models can call to perform actions
• Resources: Data sources like files, databases, or API endpoints
• Prompts: Pre-defined prompt templates
• Authentication: Secure credential management

Configuring MCP Servers

Server Configuration

MCP servers are configured in the Open WebUI admin panel:

1. Access Admin Settings

   Navigate to Admin Panel → Settings → MCP Servers

2. Add Server Connection

   Configure the server connection:

   {
     "type": "mcp",
     "info": {
       "id": "my-mcp-server",
       "name": "My MCP Server",
       "description": "Custom MCP server integration"
     },
     "auth_type": "none",
     "config": {
       "enable": true,
       "access_grants": []
     }
   }
   
3. Configure Authentication

   Choose authentication method:

   No Authentication

   {
     "auth_type": "none"
   }
   
4. Set Access Control

   Define who can use the server:

   {
     "config": {
       "enable": true,
       "access_grants": [
         {
           "principal_type": "user",
           "principal_id": "user-id-123",
           "permission": "read"
         },
         {
           "principal_type": "group",
           "principal_id": "group-id-456",
           "permission": "write"
         }
       ]
     }
   }
   

Using MCP Servers

Listing Available Servers

MCP servers appear in the tools list with the server:mcp: prefix:

import requests

response = requests.get("http://localhost:8080/api/tools/")
tools = response.json()

# Filter MCP servers
mcp_servers = [
    tool for tool in tools
    if tool["id"].startswith("server:mcp:")
]

for server in mcp_servers:
    print(f"{server['name']}: {server['meta']['description']}")

Server Authentication Status

For OAuth-enabled servers, check authentication status:

response = requests.get("http://localhost:8080/api/tools/")
tools = response.json()

for tool in tools:
    if tool["id"].startswith("server:mcp:"):
        authenticated = tool.get("authenticated", False)
        print(f"{tool['name']}: {'✓ Authenticated' if authenticated else '✗ Not authenticated'}")

OAuth Authentication Flow

For OAuth 2.1 enabled servers, users need to authenticate:

1. Initiate OAuth Flow

   User clicks “Connect” in the UI for the MCP server

2. Authorize Access

   User is redirected to the OAuth provider to grant permissions

3. Store Token

   Open WebUI receives and stores the OAuth token for the user

4. Use Server

   Server tools are now available with user-specific credentials

MCP Server Examples

File System Server

Provide access to local or cloud file systems:

{
  "type": "mcp",
  "info": {
    "id": "filesystem",
    "name": "File System",
    "description": "Access to project files"
  },
  "auth_type": "none",
  "config": {
    "enable": true,
    "base_path": "/app/data/projects",
    "allowed_extensions": [".txt", ".md", ".json", ".py"]
  }
}

Database Server

Connect to SQL databases:

{
  "type": "mcp",
  "info": {
    "id": "postgres-db",
    "name": "PostgreSQL Database",
    "description": "Company database access"
  },
  "auth_type": "oauth_2.1",
  "config": {
    "enable": true,
    "connection_string": "postgresql://localhost:5432/mydb",
    "read_only": true,
    "access_grants": [
      {
        "principal_type": "group",
        "principal_id": "developers",
        "permission": "read"
      }
    ]
  }
}

API Gateway Server

Access external APIs through MCP:

{
  "type": "mcp",
  "info": {
    "id": "slack-api",
    "name": "Slack Integration",
    "description": "Send and read Slack messages"
  },
  "auth_type": "oauth_2.1",
  "oauth_config": {
    "client_id": "slack-client-id",
    "client_secret": "slack-client-secret",
    "authorization_url": "https://slack.com/oauth/v2/authorize",
    "token_url": "https://slack.com/api/oauth.v2.access",
    "scopes": ["channels:read", "chat:write"]
  },
  "config": {
    "enable": true
  }
}

Access Control

MCP servers support granular access control:

User-Based Access

{
  "config": {
    "access_grants": [
      {
        "principal_type": "user",
        "principal_id": "[e-mail]",
        "permission": "read"
      },
      {
        "principal_type": "user",
        "principal_id": "[e-mail]",
        "permission": "write"
      }
    ]
  }
}

Group-Based Access

{
  "config": {
    "access_grants": [
      {
        "principal_type": "group",
        "principal_id": "engineering",
        "permission": "write"
      },
      {
        "principal_type": "group",
        "principal_id": "marketing",
        "permission": "read"
      }
    ]
  }
}

Public Access

{
  "config": {
    "access_grants": [
      {
        "principal_type": "user",
        "principal_id": "*",
        "permission": "read"
      }
    ]
  }
}

Tool Discovery

MCP servers dynamically expose their tools to Open WebUI:

import requests

# Get all tools from a specific MCP server
server_id = "server:mcp:my-server"
response = requests.get(f"http://localhost:8080/api/tools/id/{server_id}")
server_info = response.json()

print(f"Server: {server_info['name']}")
print(f"Description: {server_info['meta']['description']}")
print(f"Tools available: {len(server_info.get('specs', []))}")

Security Considerations

MCP servers can access sensitive resources. Always:

• Use authentication for production servers
• Implement proper access controls
• Validate all inputs and outputs
• Monitor server usage
• Keep credentials secure

Best Practices

1. Authentication: Use OAuth 2.1 for user-specific access
2. Authorization: Implement least-privilege access control
3. Validation: Validate all data from external sources
4. Monitoring: Log all MCP server interactions
5. Encryption: Use TLS for all connections
6. Secrets: Never hardcode credentials in configuration

Troubleshooting

Server Not Appearing

• Verify enable: true in server config
• Check access grants include your user/group
• Ensure server type is set to "mcp"
• Restart Open WebUI after configuration changes

Authentication Failures

• Verify OAuth credentials are correct
• Check token hasn’t expired
• Ensure redirect URIs are properly configured
• Review OAuth provider logs

Connection Errors

• Confirm server endpoint is accessible
• Check firewall rules
• Verify network connectivity
• Review server logs for errors

Advanced Configuration

Custom MCP Server

You can build custom MCP servers using the MCP Python SDK:

from mcp.server import Server, Tool
from mcp.types import TextContent

server = Server("my-custom-server")

@server.tool()
def get_data(query: str) -> TextContent:
    """Fetch data based on query."""
    # Your custom logic here
    result = f"Data for: {query}"
    return TextContent(type="text", text=result)

if __name__ == "__main__":
    server.run()

Environment Variables

Configure MCP settings via environment variables:

# Enable MCP support
ENABLE_MCP=true

# MCP server timeout
MCP_TIMEOUT=30

# MCP connection pool size
MCP_POOL_SIZE=10

Next Steps

• Explore Tools for custom tool development
• Learn about Functions for Python function calling
• Review Skills for reusable capabilities