Docs
✨ Features
MCP

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.

  1. First, configure MCP servers in your librechat.yaml file (see example below).
  2. Restart LibreChat to initialize the connections.

In Chat Area

MCP Tools 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 in your configuration:

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

MCP Tools in Agent Builder

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:

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

For detailed configuration options and examples, see:

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

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 for complete list)

Server Instructions

serverInstructions is a LibreChat feature that dynamically adds configured instructions when any tool from that MCP server is selected:

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.

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.

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

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 authentication URL in the console
  3. Browser Authentication: Copy the URL and authenticate in your browser
  4. Token Storage: LibreChat securely stores the tokens for future use
  5. Automatic Refresh: If refresh tokens are supported, LibreChat handles renewal automatically

Example authentication prompt:

═══════════════════════════════════════════════════════════════════════
Please visit the following URL to authenticate:
 
https://mcp-server.example.com/authorize?response_type=code&client_id=...
 
═══════════════════════════════════════════════════════════════════════

Soon, you will be able to add MCP Servers and configure OAuth authentication directly from the LibreChat interface.

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.

User-specific OAuth authentication flow

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:

[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 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.

OverviewAgents