How to add an MCP server in LibreChat

LibreChat uses the Model Context Protocol to connect a model to external tools, data sources, and services without editing LibreChat's code for each integration. The features page calls MCP the "USB-C of AI". Tools from a server stay unavailable until that server is declared, authenticated when required, and then selected in chat or attached in the Agent Builder.

There are two supported paths. Put the server under mcpServers in librechat.yaml, or add it from the MCP Settings panel. Adding or editing a YAML server requires a restart so LibreChat can initialize the connection. A server added in the panel takes effect without a restart. A panel-created OAuth server is registered on save and starts disconnected; authenticate it once to connect it.

Add the server in librechat.yaml

The documented basic configuration includes Streamable HTTP entries, which set type and url, and entries that set command and args:

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

Replace the filesystem documents path, the business API URL, and the token before you rely on those examples. In that block, serverInstructions: true uses instructions advertised by the server when available. The same option can be false to disable instructions, or a string used verbatim.

A later example on the same page separates initialization from tool calls:

    initTimeout: 15000 # 15 seconds for server initialization
    timeout: 60000 # 60 seconds for tool operations

If a call is still cut short, check the proxy in front of LibreChat. The docs name nginx and traefik as examples of proxies that can sever connections on their own default timeouts.

Restart after every YAML add or edit. This page does not give the restart command, so use the one for your install rather than guessing a flag.

Smithery can also install a server into librechat.yaml. Search smithery.ai, open a server, go to the Auto tab in Connect, select LibreChat, and run the generated terminal command. That command is not printed on the LibreChat page. Restart after the install.

Add the server from the MCP Settings panel

This path does not edit a config file and does not require a restart. The documented create fields are name, description, URL, transport type, and authentication method. Whether that dialog also accepts command and args is not stated; those fields are shown in the YAML examples above.

Open the MCP Settings panel from the right sidebar. Existing servers are listed with a + button.
Press + and enter the server name, description, URL, transport type, and authentication method.
Click Create. The server appears in the panel with a confirmation toast.

To require a user-supplied key, select "API Key" in the Authentication section, check "User provides key", choose Bearer, Basic, or Custom, and save. LibreChat creates a destination-bound customUserVars entry named MCP_API_KEY_<hash> and the matching header. The user enters the key in the MCP Tool Select Dialog or the MCP Settings panel. Some existing servers still use the legacy name MCP_API_KEY.

UI-created servers can resolve only customUserVars placeholders written as {{VAR_NAME}}. They block ${ENV_VAR}, {{LIBRECHAT_USER_*}}, and {{LIBRECHAT_OPENID_*}}. Use librechat.yaml when you need those placeholders. If an API key is configured, LibreChat treats the server as API-key authenticated and skips OAuth auto-detection, unless you set an explicit OAuth configuration. An older API-key server stuck on OAuth Required can be refreshed by editing and saving it once.

Register the OAuth callback

The callback URL is:

${DOMAIN_SERVER}/api/mcp/<server-name>/oauth/callback

<server-name> is the YAML key or the name created in the panel. A server named salesforce with DOMAIN_SERVER=https://chat.example.com uses https://chat.example.com/api/mcp/salesforce/oauth/callback. Register that exact URL with the provider. Local Docker installs usually use http://localhost:3080 as the base URL.

Then check the status indicator. If the server requires OAuth, the status shows as disconnected until you authenticate. Select the server in the composer's + palette. Review the Connect prompt and choose Continue with OAuth. Finish sign-in and consent in the new tab. The success window closes, LibreChat selects the server, the status becomes connected, and a chip appears on the composer.

The documented status icons are Connected (green gear), OAuth Required (amber key), Disconnected (orange plug), Initializing (blue loader), Error (red triangle), and Cancelling (red x). A flow started in this browser stays authorizing or connecting even if cached status still says Connected, until success, failure, timeout, or cancellation. In Agent Builder, under Tool Library and MCP server configuration, Connect becomes Cancel while that flow can be cancelled. Cancel stops it and does not auto-attach tools if a late result arrives.

Select it in chat

MCP servers show in chat when you use a traditional endpoint such as OpenAI, Anthropic, Google, or Bedrock. Select a non-agent endpoint and a tool-compatible model first. In the composer's + palette, open MCP Servers and select the server. It appears as a composer chip, and all of its tools become available. You can select more than one server without building an agent.

Hide a server from that picker with chatMenu: false:

mcpServers:
  internal-tools:
    command: npx
    args: ['-y', 'internal-mcp-server']
    chatMenu: false # Not selectable in regular chat

The setting is enforced on chat requests, not only in the picker, so a stale selection cannot keep using a hidden server. It does not remove the server from saved Agents or from a model spec that assigns it. Servers reachable only through an authorized Agent are also omitted from regular chat selection.

Attach tools in the Agent Builder

Create or edit an agent.
Open Add tools and select MCP.
Select a server. Each server is one catalog entry, even when it has 20+ tools, which this page illustrates with Spotify.
Expand it and enable or disable individual tools.
Save the agent.

The panel server is available here after you connect it, so an agent can be limited to a subset of tools. If an agent expects MCP tools and none can be resolved at run start, LibreChat fails the run with connection and access guidance instead of running without them.

For a YAML server that needs credentials before the first connection, set startup: false so LibreChat waits for a manual reinitialize. Save the customUserVars value in the MCP panel, then use the reinitialize control beside the server name. For an unreachable server, missing customUserVars, an OAuth connection that must be authenticated again, or a generic initialization failure, use the named variables or reauthentication action in the message and retry. The page says you do not have to remove and re-add the server for those cases.

What to do next

Use YAML when the server should live in config: add the mcpServers entry, restart, and register the callback if the provider uses OAuth. Use the right-sidebar MCP Settings panel when the server should apply without a restart, then authenticate once if it stays disconnected. Confirm the result in a tool-compatible non-agent chat by looking for the composer chip, or in Agent Builder by opening Add tools, selecting MCP, and saving only the tools that agent should call. For placeholders, timeouts, and customUserVars beyond these examples, continue on the LibreChat MCP features page linked below.