mirror of
https://github.com/LibreChat-AI/librechat.ai.git
synced 2026-03-27 10:48:32 +07:00
3f04e0a278
* docs: update mcp servers for dynamic registration in UI and add clickhouse cloud instructions * chore: better verbiage on dynamic mcp registration docs * chore: reword sentence
518 lines
21 KiB
Plaintext
518 lines
21 KiB
Plaintext
---
|
||
title: MCP
|
||
icon: Blocks
|
||
description: Learn how LibreChat leverages Model Context Protocol (MCP) to provide seamless integration with external tools, data sources, and specialized services.
|
||
---
|
||
|
||
Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to Large Language Models (LLMs). Think of MCP as the **"USB-C of AI"** - just as USB-C provides a universal connection standard for electronic devices, MCP offers a standardized way to connect AI models to diverse tools, data sources, and services.
|
||
|
||
LibreChat leverages MCP to dramatically expand what your AI agents can do, allowing you to integrate everything from file system access, web browsers, specialized APIs, to custom business tools.
|
||
|
||
## Why MCP Matters
|
||
|
||
LLMs are limited to their built-in capabilities. With MCP, LibreChat breaks down these walls by:
|
||
|
||
- **Connecting to any tool or service** that provides an MCP server
|
||
- **Standardizing integrations** so you don't need to edit LibreChat's code for each tool
|
||
- **Supporting multi-user environments** with proper authentication and isolation
|
||
- **Providing a growing ecosystem** of dynamic, ready-to-use integrations
|
||
|
||
## How MCP Works in LibreChat
|
||
|
||
LibreChat provides two ways to use MCP servers, either in the chat area or with agents.
|
||
|
||
You can configure MCP servers manually in your `librechat.yaml` file or by using [smithery.ai](https://smithery.ai) to find and install MCP servers into `librechat.yaml` ([see example below](#basic-configuration)). Any time you add or edit an MCP server, you will need to restart LibreChat to initialize the connections.
|
||
|
||
### In Chat Area
|
||
|
||
|
||
|
||
LibreChat displays configured MCP servers directly in the chat area when using traditional endpoints (OpenAI, Anthropic, Google, Bedrock, etc.):
|
||
|
||
- Select any non-agent endpoint first, and a tool-compatible model
|
||
- MCP servers appear in a dropdown in the chat interface below your text input
|
||
- When selected, all tools from that server become available to your current model
|
||
- Quick access to MCP tools without creating an agent, allowing multiple servers to be used at once
|
||
|
||
To disable MCP servers from appearing in the chat dropdown (keeping them agent-only), set [`chatMenu: false`](/docs/configuration/librechat_yaml/object_structure/mcp_servers#chatmenu) in your configuration:
|
||
|
||
```yaml
|
||
mcpServers:
|
||
internal-tools:
|
||
command: npx
|
||
args: ["-y", "internal-mcp-server"]
|
||
chatMenu: false # Only available in agent builder
|
||
```
|
||
|
||
### With Agents
|
||
|
||
MCP servers integrate seamlessly with LibreChat Agents:
|
||
|
||
1. Create or edit an agent
|
||
2. Click "Add MCP Server Tools" to open the Tools Dialog from the Agent Builder panel
|
||
3. Select MCP servers once added, each appears as a single entry
|
||
4. Fine-tune your agent's capabilites by enabling/disabling individual tools after adding
|
||
5. Save your agent
|
||
|
||
|
||
|
||
This higher-level organization keeps the interface manageable - even servers with 20+ tools (like Spotify) appear as single entries that can be expanded for granular control.
|
||
|
||
### Basic Configuration
|
||
|
||
Add MCP servers to your `librechat.yaml` file manually:
|
||
|
||
```yaml
|
||
mcpServers:
|
||
# ClickHouse Cloud
|
||
clickhouse-cloud:
|
||
type: streamable-http
|
||
url: https://mcp.clickhouse.cloud/mcp
|
||
|
||
# File system access
|
||
filesystem:
|
||
command: npx
|
||
args:
|
||
- -y
|
||
- "@modelcontextprotocol/server-filesystem"
|
||
- /path/to/your/documents
|
||
|
||
# Web browser automation
|
||
puppeteer:
|
||
command: npx
|
||
args:
|
||
- -y
|
||
- "@modelcontextprotocol/server-puppeteer"
|
||
|
||
# Production-ready cloud service
|
||
business-api:
|
||
type: streamable-http
|
||
url: https://api.yourbusiness.com/mcp
|
||
headers:
|
||
X-User-ID: "{{LIBRECHAT_USER_ID}}"
|
||
Authorization: "Bearer ${API_TOKEN}"
|
||
timeout: 30000
|
||
serverInstructions: true
|
||
```
|
||
|
||
### Adding MCP Servers in the UI
|
||
|
||
You can also add and configure MCP servers directly from the LibreChat interface without editing any configuration files or restarting the server.
|
||
|
||
#### Step 1: Open the MCP Settings Panel
|
||
|
||
Navigate to the **MCP Settings** panel from the right sidebar. You'll see any existing MCP servers listed here along with a **+** button to add new ones.
|
||
|
||
|
||
|
||
#### Step 2: Fill Out Server Details
|
||
|
||
Press the **+** button and fill out your MCP server name, description, URL, transport type, and authentication method, then click **Create**.
|
||
|
||
|
||
|
||
Your new server will appear in the MCP Settings panel with a confirmation toast.
|
||
|
||
|
||
|
||
#### Step 3: Check Connection Status and Authenticate
|
||
|
||
Review the [connection status indicator](#connection-status-indicators) for your new server. If the server requires OAuth authentication, the status will show as disconnected. Click the server's authenticate/connect button (you can do this either by clicking on the MCP server itself in the chat dropdown menu, or by clicking on the connection icon first to be taken to a dialog with more information on the connection state) to begin the authentication flow.
|
||
|
||
|
||
|
||
Once initiated, the status indicator will update to show that authentication is in progress.
|
||
|
||
|
||
|
||
#### Step 4: Continue in the OAuth Tab
|
||
|
||
A new browser tab will open for the OAuth provider. Verify the callback URL and click **Continue** to authorize LibreChat.
|
||
|
||
|
||
|
||
#### Step 5: Authentication Successful
|
||
|
||
After authenticating, you'll see a success confirmation. This window will automatically close and redirect you back to LibreChat.
|
||
|
||
|
||
|
||
#### Step 6: Server Ready for Use
|
||
|
||
LibreChat acknowledges the successful authentication and automatically selects the MCP server for use within your conversation. The server now shows a connected status indicator and is checked in the MCP Servers dropdown.
|
||
|
||
|
||
|
||
Your new MCP server is also available in the Agent Builder, where you can add its tools to any agent and customize what subset of tools are allowed.
|
||
|
||
|
||
|
||
|
||
### Adding MCP Servers with Smithery
|
||
|
||
Smithery.ai provides a streamlined way to discover and install MCP servers for LibreChat. Follow these steps to get started:
|
||
|
||
#### Step 1: Search for MCP Servers
|
||
|
||
Visit [smithery.ai](https://smithery.ai) and search for the MCP server you want to add to your LibreChat instance.
|
||
|
||
|
||
|
||
#### Step 2: Select Your MCP Server
|
||
|
||
Click on the MCP server from the search results to view details and available tools.
|
||
|
||
|
||
|
||
#### Step 3: Configure for LibreChat
|
||
|
||
Navigate to the **Auto** tab in the **Connect** section and select **LibreChat** as your desired client.
|
||
|
||
|
||
|
||
#### Step 4: Install the MCP Server
|
||
|
||
Copy and run the generated command in your terminal to install the MCP server.
|
||
|
||
|
||
|
||
#### Step 5: Restart and Verify
|
||
|
||
Your MCP server is now installed and configurable in `librechat.yaml`. Restart LibreChat to initialize the connections and start using your new MCP server.
|
||
|
||
|
||
*MCP server installed through smithery.ai and ready for use in LibreChat*
|
||
|
||
|
||
For detailed configuration options and examples, see:
|
||
|
||
- [MCP Servers Configuration](/docs/configuration/librechat_yaml/object_structure/mcp_servers)
|
||
- [Agent Configuration](/docs/configuration/librechat_yaml/object_structure/agents)
|
||
- [Advanced Agent Features](/docs/features/agents#model-context-protocol-mcp)
|
||
|
||
## MCP Server Management
|
||
|
||
LibreChat provides comprehensive tools for managing MCP server connections with connection status tracking and OAuth authentication and initialization support in the UI.
|
||
|
||
### Connection Status Indicators
|
||
|
||
LibreChat displays dynamic status icons showing the current state of each MCP server in the chat dropdown and settings panel:
|
||
|
||
|
||
|
||
**Status Types:**
|
||
|
||
- **Connected** (green gear): Server is connected and has configurable customUserVars
|
||
- **OAuth Required** (amber key): Server requires OAuth authentication
|
||
- **Disconnected** (orange plug): Server connection failed or lost
|
||
- **Initializing** (blue loader): Server is starting up or reconnecting
|
||
- **Error** (red triangle): Server encountered an error
|
||
- **Cancelling** (red x): OAuth flow is being cancelled
|
||
|
||
### Server Initialization
|
||
|
||
You can initialize or re-initialize MCP servers directly from the interface:
|
||
|
||
**One click:**
|
||
|
||
- One-click initialization from the MCP server selection dropdown
|
||
|
||
|
||
<video
|
||
muted
|
||
controls
|
||
>
|
||
<source src="/videos/mcp_one_click_init.mp4" />
|
||
</video>
|
||
|
||
**From MCPConfigDialog:**
|
||
|
||
- Click the status icon next to an MCP server in the Chat Dropdown to open the MCPConfigDialog
|
||
- Configure custom user variables and click the Authenticate/Initialize button depending on the server authentication type
|
||
|
||
<video
|
||
muted
|
||
controls
|
||
>
|
||
<source src="/videos/mcp_config_dialog_auth.mp4" />
|
||
</video>
|
||
|
||
**From MCP Settings Panel:**
|
||
|
||
- Click any server in the server list section of MCP Settings Panel to access configuration and initialization controls
|
||
- Configure custom user variables and click the Authenticate/Initialize button depending on the server authentication type
|
||
|
||
<video
|
||
muted
|
||
controls
|
||
>
|
||
<source src="/videos/mcp_settings_init.mp4" />
|
||
</video>
|
||
|
||
### MCP Settings Panel Visibility
|
||
|
||
The MCP Settings Panel appears in the right sidebar when LibreChat detects MCP servers that might require user intervention during their initialization. The panel will be visible when any configured server meets one of these criteria:
|
||
|
||
- **Custom User Variables**: Server has `customUserVars` defined which may contain user-provided credentials
|
||
- **OAuth Authentication**: Server is detected as requiring OAuth authentication during startup
|
||
- **Manual Initialization**: Server has `startup: false` configured, requiring manual initialization
|
||
|
||
## LibreChat-Specific Features
|
||
|
||
LibreChat's MCP implementation is designed for highly configurable, real-world, multi-user environments.
|
||
|
||
### User-Specific Connections
|
||
|
||
- Each user gets their own isolated connection to MCP servers
|
||
- User authentication and permissions are respected
|
||
- Personal data and context remain private
|
||
|
||
### Dynamic User Context
|
||
|
||
MCP servers can access user information through placeholders in **URLs and headers** (for SSE and Streamable HTTP transports):
|
||
|
||
```yaml
|
||
mcpServers:
|
||
user-api:
|
||
type: streamable-http
|
||
url: https://api.example.com/users/{{LIBRECHAT_USER_USERNAME}}/mcp
|
||
headers:
|
||
X-User-ID: "{{LIBRECHAT_USER_ID}}"
|
||
X-User-Email: "{{LIBRECHAT_USER_EMAIL}}"
|
||
X-User-Role: "{{LIBRECHAT_USER_ROLE}}"
|
||
Authorization: "Bearer ${API_TOKEN}"
|
||
```
|
||
|
||
Available placeholders include:
|
||
|
||
- `{{LIBRECHAT_USER_ID}}` - Unique user identifier
|
||
- `{{LIBRECHAT_USER_EMAIL}}` - User's email address
|
||
- `{{LIBRECHAT_USER_ROLE}}` - User role (admin, user, etc.)
|
||
- `{{LIBRECHAT_USER_USERNAME}}` - Username
|
||
- And many more (see [MCP Servers Configuration](/docs/configuration/librechat_yaml/object_structure/mcp_servers#headers) for complete list)
|
||
|
||
### Server Instructions
|
||
|
||
`serverInstructions` is a LibreChat feature that dynamically adds configured instructions when any tool from that MCP server is selected:
|
||
|
||
```yaml
|
||
mcpServers:
|
||
filesystem:
|
||
command: npx
|
||
args: ["-y", "@modelcontextprotocol/server-filesystem", "/docs"]
|
||
serverInstructions: |
|
||
When accessing files:
|
||
- Always check file permissions first
|
||
- Use absolute paths for reliability
|
||
- Handle errors gracefully
|
||
```
|
||
|
||
Options:
|
||
|
||
- `true`: Use server-provided instructions
|
||
- `false`: Disable instructions
|
||
- `string`: Custom instructions (shown above)
|
||
|
||
### Timeout Configuration
|
||
|
||
For long-running MCP operations, configure appropriate timeouts for both initialization and tool operations.
|
||
|
||
```yaml
|
||
mcpServers:
|
||
data-processor:
|
||
type: streamable-http
|
||
url: https://api.example.com/mcp
|
||
initTimeout: 15000 # 15 seconds for server initialization
|
||
timeout: 60000 # 60 seconds for tool operations
|
||
```
|
||
|
||
**Note**: If operations are still being cut short, check your proxy configuration (e.g., nginx, traefik, etc.) which may be severing connections prematurely due to default timeouts.
|
||
|
||
### User Provided Credentials
|
||
|
||
You can allow users to provide their own credentials for MCP servers through `customUserVars`. This enables secure, user-specific authentication without storing credentials in configuration files.
|
||
|
||
```yaml
|
||
mcpServers:
|
||
my-api-server:
|
||
type: streamable-http
|
||
url: "https://api.example.com/mcp"
|
||
headers:
|
||
X-Auth-Token: "{{MY_API_KEY}}" # Uses the user-provided value
|
||
customUserVars:
|
||
MY_API_KEY:
|
||
title: "API Key"
|
||
description: "Enter your personal API key from <a href='https://example.com/keys' target='_blank'>your account settings</a>"
|
||
```
|
||
|
||
Users can configure these credentials:
|
||
|
||
- **From Chat Area**: Click the settings icon next to configurable MCP servers in the tool selection dropdown
|
||
- **From MCP Settings Panel**: Access "MCP Settings" in the right panel to manage credentials for all configured servers
|
||
|
||
#### Reinitializing MCP Servers with User Credentials
|
||
|
||
For MCP servers that require user-specific credentials before they can be used (e.g., `PAT_TOKEN`'s in [GitHub’s official MCP server](https://github.com/github/github-mcp-server)), LibreChat allows users to provide these credentials and then reinitialize the MCP server from within the UI without restarting the whole application:
|
||
|
||
1. When you select an MCP that uses `customUserVars`, you will be able to **Save** or **Revoke** a `customUserVar`'s value for the selected MCP server from within the MCP Panel.
|
||
2. After saving a value for a `customUserVar`, click the reinitialize button (an icon with circular arrows next to each server name in the MCP Panel).
|
||
3. LibreChat will attempt to connect to the server using your provided credentials and notify you with a toast whether the reinitialization process has succeeded or failed.
|
||
|
||
> _Tip: If you know a server will require credentials not available at first startup, you can add `startup: false` to its configuration. This tells LibreChat to not attempt to connect to that server until it is manually reinitialized in the UI._
|
||
|
||
**Example:**
|
||
|
||
```yaml
|
||
mcpServers:
|
||
github-mcp:
|
||
type: streamable-http
|
||
url: "https://api.githubcopilot.com/mcp/"
|
||
headers:
|
||
Authorization: "{{PAT_TOKEN}}"
|
||
customUserVars:
|
||
PAT_TOKEN:
|
||
title: "GitHub PAT Token"
|
||
description: "GitHub Personal Access Token"
|
||
startup: false
|
||
```
|
||
|
||
### OAuth Authentication
|
||
|
||
LibreChat supports OAuth authentication for MCP servers, following Anthropic's recommendation for secure MCP connections. OAuth provides a standardized, secure way to authenticate without storing long-lived credentials.
|
||
|
||
#### Supported OAuth Flows
|
||
|
||
LibreChat MCP servers support OAuth 2.0 with:
|
||
|
||
- **Authorization Code Flow with PKCE**: Recommended for maximum security
|
||
- **Client Discovery**: Automatic client registration when supported by the OAuth provider
|
||
- **Refresh Tokens**: Automatic token renewal when available
|
||
|
||
#### Configuration Examples
|
||
|
||
```yaml
|
||
mcpServers:
|
||
# Public remote MCP server for PayPal, uses OAuth Client Discovery
|
||
# ❌ Refresh Tokens: you may need to re-authenticate periodically
|
||
# More info: https://developer.paypal.com/tools/mcp-server/
|
||
paypal:
|
||
type: "sse"
|
||
initTimeout: 150000 # higher timeout to allow for initial authentication
|
||
url: "https://mcp.paypal.com/sse"
|
||
|
||
# Example self-hosted remote MCP server for Spotify, uses OAuth Client Discovery
|
||
# ✅ Refresh Tokens: refreshes token for authentication automatically
|
||
# Hosted on Cloudflare Workers, more info: https://github.com/LibreChat-AI/spotify-mcp
|
||
spotify:
|
||
type: "streamable-http"
|
||
initTimeout: 150000
|
||
url: "https://mcp-spotify-oauth-example.account.workers.dev/mcp"
|
||
```
|
||
|
||
#### OAuth Authentication Flow
|
||
|
||
When you first configure an OAuth-enabled MCP server:
|
||
|
||
1. **Initial Connection**: LibreChat attempts to connect to the MCP server
|
||
2. **Authentication Required**: If no valid token exists, you'll see an OAuth authentication indicator in the chat dropdown for that server
|
||
3. **Button Interface**: Click the authentication indicator button to open the MCPConfigDialog and begin the OAuth flow
|
||
4. **Config Dialog**: Click the Authenticate button in the MCPConfigDialog to open the OAuth authentication page in your browser
|
||
5. **Browser Redirect**: LibreChat opens the OAuth provider in your browser
|
||
6. **Return Handling**: LibreChat automatically processes the OAuth callback once you've authenticated
|
||
7. **Token Storage**: LibreChat securely stores the tokens for future use
|
||
8. **Connection Established**: Once you've authenticated, the MCP server will be connected and you can use it in your chat
|
||
|
||
#### OAuth Callback URL
|
||
|
||
When an MCP server uses OAuth, LibreChat exposes a callback endpoint that the OAuth provider redirects to after successful authorization.
|
||
|
||
The callback URL must follow this format:
|
||
|
||
`${baseUrl}/api/mcp/${serverName}/oauth/callback`
|
||
|
||
Where `${serverName}` is the MCP server key defined in your `librechat.yaml` configuration. LibreChat handles the redirect at this endpoint, completes the token exchange, and associates the credentials with the corresponding MCP server.
|
||
|
||
<Callout type="info" title="OAuth Callback URL Example">
|
||
Given the following MCP server configuration:
|
||
|
||
```yaml
|
||
mcpServers:
|
||
# Example self-hosted remote MCP server for Spotify, uses OAuth Client Discovery
|
||
# ✅ Refresh Tokens: refreshes token for authentication automatically
|
||
# Hosted on Cloudflare Workers, more info: https://github.com/LibreChat-AI/spotify-mcp
|
||
spotify:
|
||
type: 'streamable-http'
|
||
initTimeout: 150000
|
||
url: 'https://mcp-spotify-oauth-example.account.workers.dev/mcp'
|
||
```
|
||
|
||
|
||
The callback URL would be `${baseUrl}/api/mcp/spotify/oauth/callback`.
|
||
</Callout>
|
||
|
||
Note:
|
||
|
||
- The callback URL must be registered exactly with the OAuth provider for the flow to work.
|
||
- Other paths such as `/api/oauth/callback` or `/api/oauth/openid/callback` are not valid for MCP OAuth flows.
|
||
|
||
#### Token Management
|
||
|
||
LibreChat handles OAuth tokens intelligently:
|
||
|
||
- **Secure Storage**: Tokens are encrypted and stored securely
|
||
- **Automatic Refresh**: When refresh tokens are available, LibreChat automatically renews expired access tokens
|
||
- **Session Management**: Each user maintains their own OAuth sessions for multi-user environments
|
||
|
||
Each user will be prompted to authenticate with their own OAuth login when they first use an OAuth-enabled MCP server. This ensures that connection and authentication details are unique to each user, maintaining security and privacy in multi-user environments.
|
||
|
||
|
||
|
||
> Note: The tokens shown during app startup are for app-level initialization only and are not used for individual user connections.
|
||
|
||
Example of automatic token refresh:
|
||
|
||
```bash
|
||
[MCP][spotify] Access token missing
|
||
[MCP][spotify] Attempting to refresh token
|
||
[MCP][spotify] Successfully refreshed and stored OAuth tokens
|
||
[MCP][spotify] ✓ Initialized
|
||
```
|
||
|
||
#### Best Practices
|
||
|
||
1. **Use OAuth when available**: Prefer OAuth over API keys for better security
|
||
2. **Configure appropriate timeouts**: Set higher `initTimeout` for OAuth flows (e.g., 150000ms)
|
||
3. **Monitor token expiration**: Check logs for authentication issues
|
||
4. **Plan for re-authentication**: Some providers don't support refresh tokens
|
||
|
||
**Note**: UI-based OAuth configuration is coming soon, which will streamline the authentication process directly from the LibreChat interface.
|
||
|
||
## Server Transports
|
||
|
||
MCP servers can be configured to use different transport mechanisms:
|
||
|
||
**STDIO Servers**
|
||
|
||
- Work wells for local, single-user environments
|
||
- Not scalable for remote or cloud deployments
|
||
|
||
**Server-Sent Events (SSE) Servers**
|
||
|
||
- Remote transport mechanism but not recommended for production environment
|
||
|
||
**Streamable HTTP Servers**
|
||
|
||
- Uses HTTP POST for sending messages and supports streaming responses
|
||
- Operates as an independent process that can handle multiple client connections
|
||
- Supports both basic requests and streaming via Server-Sent Events (SSE)
|
||
- More performant alternative to the legacy HTTP+SSE transport
|
||
- Supports proper multi-user server configurations
|
||
|
||
**For production environments**, only MCP servers with ["Streamable HTTP" transports](https://modelcontextprotocol.io/specification/draft/basic/transports#streamable-http) are recommended. Unlike SSE which maintains long-running connections, Streamable HTTP offers stateless options that are better suited for scalable, multi-user deployments.
|
||
|
||
LibreChat is at the forefront of implementing flexible, scalable MCP server integrations to support diverse usage scenarios and help you build the AI workflows of tomorrow.
|
||
|
||
---
|
||
|
||
**Ready to extend your AI capabilities?** Start by configuring your first MCP server and discover how LibreChat can connect to virtually any tool or service your organization needs.
|