> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/open-webui/open-webui/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

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

## 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:

<Steps>
  <Step title="Access Admin Settings">
    Navigate to **Admin Panel → Settings → MCP Servers**
  </Step>

  <Step title="Add Server Connection">
    Configure the server connection:

    ```json theme={null}
    {
      "type": "mcp",
      "info": {
        "id": "my-mcp-server",
        "name": "My MCP Server",
        "description": "Custom MCP server integration"
      },
      "auth_type": "none",
      "config": {
        "enable": true,
        "access_grants": []
      }
    }
    ```
  </Step>

  <Step title="Configure Authentication">
    Choose authentication method:

    <CodeGroup>
      ```json No Authentication theme={null}
      {
        "auth_type": "none"
      }
      ```

      ```json OAuth 2.1 theme={null}
      {
        "auth_type": "oauth_2.1",
        "oauth_config": {
          "client_id": "your-client-id",
          "client_secret": "your-client-secret",
          "authorization_url": "https://provider.com/oauth/authorize",
          "token_url": "https://provider.com/oauth/token",
          "scopes": ["read", "write"]
        }
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Set Access Control">
    Define who can use the server:

    ```json theme={null}
    {
      "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"
          }
        ]
      }
    }
    ```
  </Step>
</Steps>

## Using MCP Servers

### Listing Available Servers

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

```python theme={null}
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:

```python theme={null}
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:

<Steps>
  <Step title="Initiate OAuth Flow">
    User clicks "Connect" in the UI for the MCP server
  </Step>

  <Step title="Authorize Access">
    User is redirected to the OAuth provider to grant permissions
  </Step>

  <Step title="Store Token">
    Open WebUI receives and stores the OAuth token for the user
  </Step>

  <Step title="Use Server">
    Server tools are now available with user-specific credentials
  </Step>
</Steps>

## MCP Server Examples

### File System Server

Provide access to local or cloud file systems:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "config": {
    "access_grants": [
      {
        "principal_type": "group",
        "principal_id": "engineering",
        "permission": "write"
      },
      {
        "principal_type": "group",
        "principal_id": "marketing",
        "permission": "read"
      }
    ]
  }
}
```

### Public Access

```json theme={null}
{
  "config": {
    "access_grants": [
      {
        "principal_type": "user",
        "principal_id": "*",
        "permission": "read"
      }
    ]
  }
}
```

## Tool Discovery

MCP servers dynamically expose their tools to Open WebUI:

```python theme={null}
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

<Warning>
  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
</Warning>

### 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:

```python theme={null}
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:

```bash theme={null}
# Enable MCP support
ENABLE_MCP=true

# MCP server timeout
MCP_TIMEOUT=30

# MCP connection pool size
MCP_POOL_SIZE=10
```

## Next Steps

* Explore [Tools](/advanced/tools) for custom tool development
* Learn about [Functions](/advanced/functions) for Python function calling
* Review [Skills](/advanced/skills) for reusable capabilities