mirror of
https://github.com/LibreChat-AI/librechat.ai.git
synced 2026-03-27 10:48:32 +07:00
b8e656306c
- Updated changelog for version 1.2.8 to include enhancements in MCP server management, such as connection status tracking and OAuth support. - Added detailed documentation on connection status indicators, server initialization processes, and user interface improvements for managing MCP servers. - Introduced new images and videos to illustrate the updated features and functionalities.
371 lines
15 KiB
Plaintext
371 lines
15 KiB
Plaintext
---
|
|
title: Model Context Protocol (MCP) - Extend LibreChat with Universal AI Tools
|
|
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)
|
|
|
|
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 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 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:
|
|
# 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 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>
|
|
## 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
|
|
|
|
### 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
|
|
|
|
#### 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. |