MCP

Connect LibreChat to external tools and data through Model Context Protocol (MCP) servers, in chat or on an agent.

MCP (Model Context Protocol) is an open standard for exposing tools to a model. An MCP server might give the model a filesystem, a browser, a database, or your company's internal API, and LibreChat can use any server that speaks the protocol. You attach servers to a regular chat for quick use, or add their tools to an agent.

Use a server in chat

On any endpoint other than Agents or Assistants, open the composer's + palette (Attach and tools) and look under MCP Servers. Click a server to turn it on for the conversation. It shows up as a chip on the composer, and every tool the server exposes becomes available to the model. The palette stays open, so you can turn on several servers in one go; click a server again, or remove its chip, to turn it off. See Composer for the rest of the palette.

The palette shows a few servers at a time, with a colored dot for each server's status. Show All on the MCP Servers header opens the full list with a search field and three views: All, Made by you, and Favorites.

The MCP Servers dialog opened with Show All, listing a Github server marked Disconnected and a Spotify server marked Needs Auth, with All, Made by you, and Favorites filters

If the server is not connected yet, clicking it starts the connection instead of selecting it right away. A server that needs your own credentials opens a dialog to enter them first; a server that uses OAuth sends you through sign-in. Once it connects, LibreChat selects it for you.

Pick a model that supports tool calls, or the model will never call the server's tools. Agents and Assistants carry their own tool setup, so the picker is hidden on those endpoints, and an admin can hide individual servers from chat so they are only available to agents.

Add a server to an agent

In the Agent Builder, click Add next to Tools to open the Tool Library, then filter to MCP servers. Adding a server lists the tools it exposes; keep the ones the agent should have and remove the rest, or use Select all and Deselect all. A server with dozens of tools still takes a single entry in the agent's tool list.

Each MCP tool on an agent also has its own options (Defer loading, Programmatic, Background, Intent label). See Agents for what they change.

Some servers depend on values that only exist during a chat request, so their tools cannot be listed ahead of time. For those, the Tool Library attaches the whole server and notes that its tools are resolved at runtime, during chat.

If an agent is set up to use MCP tools and none of them are available when a run starts (the server is down, or you lost access), the run stops with an error telling you to check the connection and your access, rather than answering without the tools. Pressing Stop during a tool call also cancels the call on the MCP server, as long as the server supports cancellation.

Connection status

In the palette and in MCP Settings, the status is a colored dot: grey when the server is disconnected, amber when it needs you to sign in. The full status is read out to screen readers, and the Tool Library and the Show All list spell it out next to each server:

Connected: ready to use.
Needs Auth: the server uses OAuth and you have not signed in, or your sign-in expired.
Connecting / Initializing: a connection attempt is in progress.
Disconnected or Error: there is no live connection, or the last attempt failed. Use Connect to try again.
On-demand: the server connects separately for each request, so there is no standing connection to report.
Unknown: no status has come back yet.

When a connection fails, the error says why: the server could not be reached, it needs variables you have not set (named in the message), or it needs you to sign in again. Fix that and connect again; there is no need to remove and re-add the server. A server can also add or remove tools while it runs, and LibreChat picks up the new list without a restart.

Connections are per user. Your OAuth tokens and saved credentials are never used for anyone else, and an idle connection is closed after 15 minutes by default and reopened the next time you use the server.

When a server needs OAuth, connecting it opens a Connect dialog. Click Continue with OAuth to open the provider's sign-in page in a new tab, or use Copy link or Show QR Code to finish on another device. After you approve access, the tab shows Authentication Successful and closes itself, and the server switches to Connected.

While a sign-in is pending, the server shows a spinner; hover it to cancel. In the Agent Builder's MCP server settings, Connect turns into Cancel for the same purpose. You have 10 minutes to finish signing in before the attempt times out (the admin can change this).

If the provider issues refresh tokens, LibreChat renews your access in the background, and when a server rejects your token mid-session it tries one refresh and reconnect before asking you to sign in again. Providers that do not issue refresh tokens ask you to sign in again when the token expires.

By default the sign-in prompt appears when your message is sent. An admin can set some servers to wait until the agent first calls one of their tools, so you are only asked to sign in when the server is actually needed.

Credentials and variables

Some servers need a value from each user, such as a personal API key or a project ID. When you connect one of these, LibreChat asks for the values before it connects. To change them later, use Configure on the server in the chat picker or in MCP Settings. Each field has Save and Revoke. Either one closes your current connection to that server, so the next use connects with the new values, and revoking also turns the server off in the current chat.

Values are stored per user and only sent to the server they were entered for.

MCP Settings panel

MCP Settings in the side panel lists every server you can use, with a status dot on each server's icon. Depending on the server's state, each card offers Connect, Reconnect, Configure (for your variables), or Revoke (to drop your OAuth tokens). Servers you are allowed to edit also have Edit.

The MCP Settings side panel listing three MCP server cards with status dots on their icons, and the Add MCP (+) button at the top

The panel appears when you have access to at least one server, or when you are allowed to create servers.

Create a server from the UI

If your role allows it, click Add MCP (the + button) in MCP Settings to register a remote server without touching librechat.yaml or restarting.

Describe the server

Enter a Name, an optional Description, and an icon if you want one. Fill in the MCP Server URL and pick a Transport: Streamable HTTPS or SSE.

Choose authentication

Under Authentication, pick one of:

None (Auto-detect): LibreChat probes the server and switches to OAuth if the server asks for it.
API Key: enter one shared key, or check Each user provides their own key so every user enters theirs through Configure. Choose the Header Format: Bearer, Basic, or Custom with your own header name.
OAuth: enter the Client ID, Client Secret, Authorization URL, Token URL, and Scope. Leave the client fields empty if the provider supports dynamic client registration. Token Exchange Method is Auto by default, which uses what the provider advertises and falls back to a Basic authorization header; pick Default (POST request) or Basic authorization header to force one.
On-Behalf-Of (OBO): only shown if an admin gave you that permission, and only works when LibreChat signs users in with OpenID Connect (for example Entra ID). Enter the scopes to request; LibreChat exchanges your OpenID token for one scoped to the MCP server.

Create it

Check I trust this application and click Create. The server is available right away. For OAuth servers, the next dialog shows the Redirect URI to register with your OAuth provider, and the server stays disconnected until you sign in once.

The Add MCP Server dialog with a name and URL filled in, Transport set to Streamable HTTPS, and Authentication set to API Key with Each user provides their own key checked

Servers created this way can only reach remote URLs; local stdio servers have to be defined in librechat.yaml. They also cannot use server environment variables or user profile placeholders: values like ${API_TOKEN} or {{LIBRECHAT_USER_EMAIL}} in their headers are stripped, since a shared server would otherwise receive them. If you change a server's URL or authentication later, users who entered their own key have to enter it again, and OAuth users have to sign in again. When you change the URL or OAuth endpoints of a server with a saved client secret, you have to re-enter the secret too. If an API-key server created with an older version is stuck on Needs Auth, open it with Edit and save it once.

Servers created in the UI belong to whoever created them. The owner can share one from its Edit dialog with specific users, groups, roles, or everyone, as a viewer (can see and use it), an editor (can also change it), or an owner. Servers defined in librechat.yaml are available to everyone with permission to use MCP. See Access Control for how the permission levels combine.

Server instructions

An admin can attach instructions to a server, either the server's own or custom text. When a conversation or agent has that server's tools, the instructions are added to the model's context, which helps with servers whose tools only make sense used in a certain order.

MCP Apps

Some servers return an interactive view along with a tool result. When MCP Apps are turned on, the tool call shows an Open app button that loads the view in a sandboxed frame, and Close app hides it again. Only a few apps can be open at once; if you hit the limit, close one first.

An app cannot act on its own. When it wants to run a tool you see Run tool from app?, and when it wants to post a message, Send message from app?. Nothing happens until you approve. Sending a message starts a model response in the current conversation, so the selected agent and its tools may be used. Apps do not render in shared conversations.

Setup

MCP needs at least one server. Admins define servers under mcpServers in librechat.yaml, which takes a restart to apply, and users with permission can add remote servers from MCP Settings. See MCP Servers for server options, the OAuth callback URL, and transports, MCP Settings for allowed domains and MCP Apps, MCP App Sandbox for app limits, and interface.mcpServers for who can use, create, and share servers. Setup guides for specific servers are under MCP Servers, and Agent Plugins covers bundling MCP servers with skills.

On this page