MCP Servers - 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:

Access Admin Settings

Navigate to Admin Panel → Settings → MCP Servers

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": []
  }
}

Configure Authentication

Choose authentication method:

{
  "auth_type": "none"
}

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:

Initiate OAuth Flow

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

Authorize Access

User is redirected to the OAuth provider to grant permissions

Store Token

Open WebUI receives and stores the OAuth token for the user

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": "alice@example.com",
        "permission": "read"
      },
      {
        "principal_type": "user",
        "principal_id": "bob@example.com",
        "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

Authentication: Use OAuth 2.1 for user-specific access
Authorization: Implement least-privilege access control
Validation: Validate all data from external sources
Monitoring: Log all MCP server interactions
Encryption: Use TLS for all connections
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

​Overview

​What is MCP?

​Configuring MCP Servers

​Server Configuration

​Using MCP Servers

​Listing Available Servers

​Server Authentication Status

​OAuth Authentication Flow

​MCP Server Examples

​File System Server

​Database Server

​API Gateway Server

​Access Control

​User-Based Access

​Group-Based Access

​Public Access

​Tool Discovery

​Security Considerations

​Best Practices

​Troubleshooting

​Server Not Appearing

​Authentication Failures

​Connection Errors

​Advanced Configuration

​Custom MCP Server

​Environment Variables

​Next Steps

Overview

What is MCP?

Configuring MCP Servers

Server Configuration

Using MCP Servers

Listing Available Servers

Server Authentication Status

OAuth Authentication Flow

MCP Server Examples

File System Server

Database Server

API Gateway Server

Access Control

User-Based Access

Group-Based Access

Public Access

Tool Discovery

Security Considerations

Best Practices

Troubleshooting

Server Not Appearing

Authentication Failures

Connection Errors

Advanced Configuration

Custom MCP Server

Environment Variables

Next Steps