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 to find and install MCP servers into librechat.yaml (see example below). 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 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 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:

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

Credential Variables for UI-Created Servers

When adding an MCP server through the UI, you can require users to provide their own API keys. In the Authentication section of the MCP Server Builder dialog, select "API Key" and check "User provides key". Choose the header format (Bearer, Basic, or Custom) and save the server.

Behind the scenes, LibreChat automatically creates a customUserVars entry named MCP_API_KEY and configures the appropriate header template (e.g., Authorization: Bearer {{MCP_API_KEY}}). Each user provides their own key through the MCP Tool Select Dialog when configuring an agent — the same UI used for YAML-defined customUserVars.

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 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
• Agent Configuration
• Advanced Agent Features

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

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

  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

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

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

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

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

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.

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'

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:

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