How to Set Up LibreChat MCP: A Configuration Guide

Model Context Protocol (MCP) lets you connect LibreChat to external tools, databases, and APIs. MCP servers expose capabilities that Claude and other models can call directly in conversations. LibreChat supports three transport types: local stdio, remote SSE, and streamable-HTTP. This guide walks you through configuring MCP servers in librechat.yaml, setting up authentication, and troubleshooting common issues on a self-hosted instance.

What is MCP and Why Use It in LibreChat?

Model Context Protocol is an open standard developed by Anthropic for exposing tools and data to LLMs. Instead of baking every integration into LibreChat itself, you run MCP servers as separate processes. Those servers define what tools the model can access. Claude calls those tools based on what it needs to do.

A real example: you're in a LibreChat conversation and ask Claude to find a file in your company's shared filesystem. The filesystem MCP server exposes a "search_files" tool. Claude calls it. The server queries your actual filesystem, returns results, and Claude summarizes them in your chat. All in one conversation.

LibreChat is unique among open-source chat platforms in how deeply it integrates MCP. You can use MCP servers in one-off chats, add servers to agents so they run background tasks, set per-user credentials so one server instance serves multiple team members, and switch transports depending on your architecture. This flexibility is why 46.6K developers on GitHub have starred LibreChat. The MIT license and active development--6,564 commits, 9.6K forks--mean you get both stability and rapid iteration on features like MCP.

The tradeoff is configuration work. Running MCP servers requires editing YAML, understanding authentication flows, and debugging connection issues when they happen. This guide covers all three.

Understanding Transport Protocols: Stdio vs. SSE vs. Streamable-HTTP

MCP servers can communicate with LibreChat using three different protocols. Each has a specific use case.

Stdio (Standard Input/Output): The simplest transport. The server runs as a subprocess on the same machine as LibreChat. Communication happens over stdin/stdout. No network. No authentication overhead. Perfect for local development or a single-machine self-hosted setup.

Pros: Zero configuration, instant startup, lowest latency. Cons: Server must run on the same machine, cannot share across instances.

SSE (Server-Sent Events): An HTTP protocol where the server sends data as events over a persistent connection. The MCP server runs anywhere on the network. LibreChat opens an HTTP connection and listens for events.

Pros: Remote deployment, can scale to multiple LibreChat instances. Cons: Stateless, requires HTTPS in production, less ideal for high-frequency tool calls.

Streamable-HTTP (or HTTP with Streaming): A bidirectional protocol using HTTP with streaming bodies. The server runs remotely and handles requests over standard HTTP POST.

Pros: Works through most corporate firewalls, lowest latency for remote servers, works with any HTTP reverse proxy. Cons: Requires more careful error handling on the client side.

Choose stdio for your laptop. Choose SSE for a cloud-hosted MCP server and single LibreChat instance. Choose streamable-HTTP if you have multiple LibreChat instances or run behind a load balancer.

How to Configure MCP Servers in librechat.yaml

The core of any LibreChat MCP setup is the librechat.yaml configuration file. This is where you define servers, their transports, and their authentication.

The YAML structure looks like this:

mcpServers:
  myServer:
    transport: stdio
    command: node
    args:
      - /path/to/server.js
    env:
      CUSTOM_VAR: value

Breaking down each field: mcpServers is the top-level key where everything lives. myServer is the name you give this server, which shows in the UI. transport is one of stdio, sse, or streamable-http. command and args specify how to start the server (for stdio only). env contains environment variables passed to the server process.

For remote servers (SSE or streamable-HTTP), the structure changes:

mcpServers:
  remoteServer:
    transport: sse
    url: https://<your-mcp-server>/sse
    credentials:
      apiKey: your-api-key

Global MCP settings live under a separate mcp key:

mcp:
  settings:
    allowedDomains:
      - "*.example.com"
      - "mcp-server.internal"
    timeout: 30000

The allowedDomains list is a security control. LibreChat will refuse to connect to MCP servers outside this list. This prevents your chat instance from reaching unintended services. Start with a single stdio server to learn the format. Once you understand the structure, adding remote servers is straightforward: swap command/args for url, and add credentials if needed.

Setting Up Three Common MCP Servers

Server 1: Filesystem (Stdio)

The filesystem MCP server exposes a filesystem to Claude. You can ask it to read files, write files, and list directories. First, download or clone the official MCP filesystem server from the ModelContextProtocol repository. The Python version works anywhere. Once you have it, add this to librechat.yaml:

mcpServers:
  filesystem:
    transport: stdio
    command: python
    args:
      - /path/to/mcp/servers/filesystem/server.py
    env:
      ALLOWED_DIRECTORIES: "/home/user/documents:/tmp/projects"

The ALLOWED_DIRECTORIES env variable restricts which folders Claude can access. Use absolute paths, separated by colons. Test it: restart LibreChat, open a chat, and select the filesystem server from the server dropdown. Ask Claude to list files. If it works, you see the directory listing in the response.

Server 2: PostgreSQL Database (Streamable-HTTP)

A database MCP server lets Claude query your PostgreSQL instance and run prepared statements. For this example, assume you have a remote MCP server running at https://<mcp-db-server>/postgres. Your database credentials are stored in environment variables on that server. In librechat.yaml:

mcpServers:
  postgres:
    transport: streamable-http
    url: https://<mcp-db-server>/postgres
    credentials:
      clientId: "your-client-id"
      clientSecret: "your-client-secret"
    env:
      REQUEST_TIMEOUT: "10000"

Test it by asking Claude "Show me the last 10 orders from the orders table." The server receives the query, validates it against a whitelist of allowed statements to prevent SQL injection, runs it, and returns rows. Claude formats the result for you. If the connection fails, check the MCP server logs. Look for "401 Unauthorized" (wrong credentials), "connection refused" (server is down), or "timeout" (slow network or slow query).

Server 3: GitHub API (OAuth)

GitHub has an official MCP server that lets Claude search repos, read issues, and post comments using your GitHub account. Clone it from the ModelContextProtocol GitHub repository. Then configure OAuth:

mcpServers:
  github:
    transport: streamable-http
    url: https://<your-github-mcp-server>/github
    credentials:
      authType: oauth
      clientId: "your-github-app-client-id"
      clientSecret: "your-github-app-client-secret"

You need to create a GitHub App in your GitHub settings under Developer Settings > OAuth Apps. The OAuth flow works like this: you provide your GitHub App credentials to the MCP server. LibreChat redirects you to GitHub to authorize the app. GitHub issues a code to LibreChat. LibreChat exchanges the code for a user access token. Claude can now call GitHub tools on your behalf. Set the OAuth redirect URI to your LibreChat server URL, for example https://<librechat-instance>/mcp/oauth/callback. After setup, ask Claude "Find open issues in my repo about authentication" or "Post a comment on issue #42." Claude will execute those requests using your GitHub credentials.

Per-User Authentication: Credentials and OAuth

By default, all users of your LibreChat instance share the same MCP server credentials. If you configure one Slack MCP server, everyone in your org accesses Slack through that one server account. That's a problem if you want per-user data isolation.

LibreChat supports per-user credentials using environment variable interpolation. When you define credentials with a curly-brace syntax, LibreChat treats them as variables to be replaced at runtime. Example:

mcpServers:
  slack:
    transport: streamable-http
    url: https://<mcp-slack-server>
    credentials:
      token: "{SLACK_TOKEN}"

LibreChat looks for an environment variable called SLACK_TOKEN on each user's session. If the variable exists, the token is passed to the server. If not, the server request fails and the user needs to authenticate.

For enterprise deployments, you can use JWT (JSON Web Token) forwarding. LibreChat can extract the user's identity token and forward it to the MCP server. The server then validates the token and issues its own credentials. To enable JWT forwarding, add this to your MCP server config:

mcpServers:
  myServer:
    transport: streamable-http
    url: https://my-mcp-server.com
    env:
      FORWARD_JWT: "true"

LibreChat will append an Authorization: Bearer header to all requests to that server. The server validates the JWT and determines which user is making the request. This is secure because JWTs are cryptographically signed, the server can verify the signature without contacting LibreChat, and the JWT includes only what you put in it like username, email, or org ID. Per-user auth takes more infrastructure work. Plan for it if you have multiple teams or users and need data isolation.

Enabling MCP in Docker: From Compose to Chat

If you run LibreChat in Docker, the setup is slightly different. The MCP server needs to be reachable from inside the LibreChat container. For a local stdio server, mount the server code as a volume:

version: '3.8'
services:
  librechat:
    image: ghcr.io/librechat-ai/librechat:latest
    volumes:
      -./librechat.yaml:/app/librechat.yaml
      -./mcp-servers:/app/mcp-servers
    environment:
      - CONFIG_PATH=/app/librechat.yaml
    ports:
      - "3000:3000"

In librechat.yaml, reference the mounted path:

mcpServers:
  filesystem:
    transport: stdio
    command: python
    args:
      - /app/mcp-servers/filesystem/server.py

For remote servers (SSE or streamable-HTTP), no volume mount is needed. Just ensure the url in your config is reachable from inside the container. If you have another Docker service running the MCP server, use the service name as the hostname:

mcpServers:
  postgres:
    transport: streamable-http
    url: http://<mcp-postgres>:5000/postgres

After updating librechat.yaml, restart the container:

docker-compose down
docker-compose up -d

Then verify the servers are loaded: go to LibreChat, open any chat, and check the server dropdown. If your servers appear there, the configuration worked. If they don't, check the LibreChat container logs:

docker-compose logs librechat

Look for lines mentioning "mcpServers" or the server names. Errors typically say "Failed to start server" or "Invalid configuration." Once the servers load, you can use them in any chat or agent on that instance.

Troubleshooting MCP Connection Errors

Error: Disconnected

The server was running but lost connection. Possible causes: the server process crashed (check the server's logs, not just LibreChat's; if it's a Python server, run it manually to see the error), a network timeout (if the server is remote and responding slowly, increase the timeout in librechat.yaml: timeout: 60000 in milliseconds), or LibreChat restarted (MCP connections reset on LibreChat restart).

Error: Needs Auth or 401 Unauthorized

Your credentials are wrong or missing. Steps: double-check the credential value in librechat.yaml (typos are common), if using OAuth, verify the callback URL matches what you registered in the OAuth app settings, and if using per-user credentials, confirm the environment variable exists on the user's session.

Error: Connecting (stuck indefinitely)

The server is not responding. Causes: the server is not running (start it and check it responds; curl the HTTP endpoint or run the stdio server manually), a firewall or network policy blocks the connection (if the server is remote, test connectivity from the LibreChat machine using telnet or curl), or the URL in the config is wrong (typos in url are silently treated as unreachable).

Error: Invalid request or Server returned unexpected format

The server is responding but not with valid MCP messages. Causes: server code is outdated (update to the latest version from the official repository) or the request body is malformed (this usually means a bug in LibreChat; report it on GitHub).

General debugging steps: verify the server works outside LibreChat by running it manually and testing one tool call, check LibreChat logs using docker-compose logs librechat or tailing the log file, and check the MCP server logs (this is the most useful signal; errors there explain why the server rejected a request).

Frequently Asked Questions

What is MCP and why would you integrate it with LibreChat?

MCP is an open standard for exposing tools and data to LLMs. LibreChat integrates it natively so Claude can call databases, APIs, and filesystems directly in conversations without baking every integration into LibreChat itself.

What are the key features and transport protocols supported by LibreChat?

LibreChat supports stdio (local), SSE (remote), and streamable-HTTP (remote with load balancing). Stdio is simplest for single-machine setups. SSE and streamable-HTTP work for remote or multi-instance deployments.

How do you configure MCP servers in librechat.yaml?

Define them under the mcpServers key with a name, transport type, and protocol-specific details like command/args for stdio or url for remote. Add global settings like allowedDomains under the mcp key.

What is the difference between stdio, SSE, and streamable-http?

Stdio runs the server as a subprocess on the same machine (simplest, zero latency). SSE runs the server remotely and uses HTTP events (works across instances). Streamable-HTTP is bidirectional HTTP streaming (works through firewalls, best for high frequency calls).

How do you authenticate MCP servers with OAuth or API keys?

Add a credentials section to the server config with the API key or OAuth app credentials. For per-user auth, use variable substitution like {SLACK_TOKEN} or enable JWT forwarding.

How do you enable MCP in Docker and docker-compose?

Mount the librechat.yaml file and any local server code as volumes. For remote servers, ensure the url is reachable from inside the container. For stdio servers, mount the mcp-servers directory and reference the path in your command.

What models support tool calling for MCP servers?

Claude 3.5 and later. Other models like GPT-4 and Gemini do not have native MCP support in LibreChat yet.

How do you troubleshoot MCP server connection errors?

Check server logs first (not just LibreChat logs). Verify credentials and network connectivity. Look for "Disconnected" (server crashed), "401 Unauthorized" (bad credentials), or "Connecting" (unreachable server). Enable verbose logging on the server for detailed diagnostics.

The Bottom Line

Setting up MCP servers in LibreChat takes work: you write YAML, choose transports, handle authentication, and troubleshoot connection issues. But the payoff is real. Claude can now access your databases, files, and APIs without you writing custom integrations. Your team asks questions in natural language and gets results instantly.

Start simple with a filesystem server over stdio. Once that works, add a remote server. Finally, layer in per-user authentication if you have multiple team members. If managing LibreChat infrastructure feels like overhead, consider Opsily's managed LibreChat hosting. We handle the deployment, scaling, and configuration so you focus on using it. Get started at /hosting/librechat.