How to configure MCP servers in LibreChat and connect external tools

If you've ever wondered how to get artificial intelligence to stop just generating text and be able to query files, use external services, or run toolsLibreChat offers a solution using the Model Context Protocol.

El Model Context Protocol, known as MCPIt is an open standard that establishes a common way to connect language models with data sources and tools. It is often compared to USB-C because it avoids having to develop a completely different integration for each application, model, or service.

Thanks to this protocol, LibreChat can connect with file systems, databases, browsers, code repositories, enterprise tools, and APIsThe model does not gain unlimited access simply by activating MCP: it can only use the functions exposed by each server and authorized by the user or administrator.

Before installing any server, it's advisable to check its origin. An MCP server can receive information from conversations and execute actions with the permissions it has been granted. For this reason, You should not install unknown servers or provide them with sensitive credentials. without first checking their code, documentation, and permissions.

What you need to use MCP servers in LibreChat

To begin, you need to have a LibreChat installation updated and access to its settings. Depending on the method chosen, you will also need permission to edit the file. librechat.yaml or authorization to create servers from the MCP panel of the interface.

The specific requirements depend on the server you want to use:

• Node.js or npx, when the server is distributed as a JavaScript package executed using stdio.
• Python and its dependencies, if the server is developed in this language.
• An accessible URL, when dealing with a remote MCP server.
• An API key or OAuth authorization, if the tool connects to a protected service.
• Network access from the container, when LibreChat is run using Docker.

You must also use a model that supports tool calls. Even if the server is properly connected, A model without tool support may not know how to invoke its functions or produce unreliable results.

Ways to add MCP servers to LibreChat

LibreChat allows you to configure MCP servers using two main procedures: from the graphical interface or by manually editing the file librechat.yaml.

The interface is the most convenient method for most users. From the MCP panel in the right sidebar, you can view existing servers and use the corresponding button to add a new one. This procedure allows you to enter the name, transport, URL, and credentials. without modifying files or restarting LibreChat.

The availability of this option may depend on the permissions configured by the administrator. LibreChat allows separate control over whether a user can use, create, share or publish MCP servers.

The configuration using librechat.yaml It provides more control and is especially useful for administrators, reproducible deployments, or shared servers. In this case, any new server or modification made to the file requires Restart LibreChat to initialize the connection.

A simple setup using stdio might look like this:

mcpServers:
  filesystem:
    type: stdio
    command: npx
    args:
      - -y
      - "@modelcontextprotocol/server-filesystem"
      - "/ruta/a/documentos"

The specified directory will be accessible to the server. Therefore, you must restrict access to a specific location and avoid granting access to... the entire file system unless it is absolutely necessary.

You can also search for servers in catalogs like Smithery. These platforms make it easy to find available projects and generate compatible configurations. However, appearing in a catalog does not guarantee that a server is secureAlways check who maintains it, what permissions it requests, and what commands it will execute.

How to use MCP tools in a chat

Once the connection is established, LibreChat allows you to use MCP servers directly in a conversation. First, you must select one. model compatible with toolsBelow the box where you write the message, the selector of available servers will appear.

Activating a server makes its tools available to the model during that conversation. You can select multiple servers simultaneously, although it's best to avoid adding unnecessary features because An excessive number of tools can increase the context and make it difficult for the model to choose correctly..

The administrator can prevent a server from appearing in this menu by adding the option:

chatMenu: false

In that case, the server will remain available to agents, but it will not appear as a selectable tool in conventional chats.

You should also review each operation before approving it, especially when a tool can delete files, modify databases, send information, or perform irreversible actions.

How to add MCP tools to an agent

MCP servers can also be used with the LibreChat AgentsFrom the Agent Builder you can open the tools section, select a server and decide which of its functions will be available.

This individual control is especially useful when a server exposes many tools. For example, you can allow one agent to query a database, but prevent others from doing so. modify or delete records.

LibreChat also supports lazy loading of tools. When a feature is marked as lazy, it doesn't occupy space in the initial model context. Instead, the agent uses a search system to locate it when needed. This option helps to reduce context consumption when connecting servers that offer dozens of functions.

The general recommendation is to apply the principle of least privilege: each agent should only have the essential tools to perform their function.

Available transport types for MCP

LibreChat currently supports the following transports stdio, Streamable HTTP, SSE and WebSocketThe choice depends on where the server is running and how it needs to communicate with LibreChat.

Transportation stdio It starts a local process and communicates with it using standard input and output. This is common on servers running with npxPython or other local commands. It's convenient for personal installations, but can become complicated in Docker or distributed environments.

For new remote servers, Streamable HTTP is usually the most recommended alternativeIt works via HTTP and is best suited for hosted services, multi-user deployments, and systems that need to scale.

A basic remote configuration might be:

mcpServers:
  herramientas-remotas:
    type: streamable-http
    url: "https://ejemplo.com/mcp"
    timeout: 60000
    initTimeout: 10000

Transportation SSE It remains supported and may be necessary for older servers that use Server-Sent Events. WebSocket is also available for services that maintain persistent communication using addresses ws:// o wss://.

If the field is omitted typeLibreChat can infer transport from the presence of command or the URL format. Even so, Stating it explicitly facilitates reading and diagnosis of the configuration.

Important parameters of librechat.yaml

The necessary parameters change depending on the transport used. On stdio servers, the main fields are command y argsThe first indicates the program to be executed, and the second contains the arguments submitted to the process.

It can also be used env to provide environment variables:

mcpServers:
  servidor-local:
    type: stdio
    command: npx
    args:
      - -y
      - "paquete-del-servidor"
    env:
      NODE_ENV: "production"

In remote transport, the essential parameter is urlThey can also be added HTTP headers, an outbound proxy, authentication, and dynamic variables.

Other important parameters are:

• timeout: maximum time allowed to perform an operation.
• initTimeout: time available to initialize the server.
• startup: It allows you to prevent the server from connecting when LibreChat starts.
• chatMenu: Check if it appears in the chat area selector.
• requiresOAuth: Indicates whether the remote server requires OAuth authentication.
• headers: It allows sending custom headers in remote connections.

You shouldn't store keys directly in a file that will be uploaded to GitHub. For secrets shared across the entire installation, it's safer to use environment variables such as ${NOMBRE_VARIABLE}.

How to connect MCP servers when using Docker

When LibreChat runs inside Docker, commands and addresses are interpreted from the container and not from the host systemThis difference explains many of the connection errors.

If you configure a stdio server that relies on Node.js, Python, or a specific application, those dependencies must be available within the container running LibreChat. They should only be installed on the host Windows or Linux system. This does not mean that the container can use them..

You should also be careful with localhostWithin a container, this address refers to the container itself. If the MCP server is running on the host machine, you may need to use an address like:

http://host.docker.internal:3001/mcp

The exact path depends on the operating system and Docker configuration. Another option is to run the MCP server inside its own container and connect both services using the same Docker Compose network.

Before modifying LibreChat, verify that the endpoint is responding from within the container itself. This will help you distinguish between a protocol problem and a problem with the protocol itself. a network, DNS, port, or dependency failure.

OAuth authentication for MCP servers

LibreChat supports OAuth 2.0 for authenticating users individually when accessing remote MCP servers. When it detects that a server requires authorization, it displays the option to initiate the process from the browser.

The return URL follows this format:

https://tu-dominio.com/api/mcp/nombre-del-servidor/oauth/callback

The name must exactly match the key used within mcpServers or with the name assigned to the server from the interface. In a local Docker installation, the typical base address might be:

http://localhost:3080/api/mcp/nombre-del-servidor/oauth/callback

This URL must be registered exactly with the OAuth provider. An incorrect protocol, a different port, or a variation in the name will usually cause problems. redirection errors or invalid callback.

OAuth tokens are stored per user, so each person accesses the external service with their own account and their own permissionsThis is especially important in shared facilities.

How to use different passwords for each user

Not all services offer OAuth. For servers that use API keys or other credentials, LibreChat provides customUserVars.

This function allows you to request a value from each user and then use it in a header or environment variable. For example:

mcpServers:
  servicio-remoto:
    type: streamable-http
    url: "https://api.ejemplo.com/mcp"
    headers:
      Authorization: "Bearer {{MCP_API_KEY}}"
    customUserVars:
      MCP_API_KEY:
        title: "Clave de API"
        description: "Introduce tu clave personal"

Each user enters their own credentials through the LibreChat settings. This way, the administrator doesn't need to store them. a single shared key for all members.

These variables can also be used on stdio servers through the section envHowever, you should check that the installed version of LibreChat is recent if you notice that the server is literally receiving the marker instead of the expected value.

Dynamic bookmarks and user permissions

LibreChat allows you to send dynamic information to the server about the person making the request. Available markers include fields such as:

{{LIBRECHAT_USER_ID}}
{{LIBRECHAT_USER_EMAIL}}
{{LIBRECHAT_USER_ROLE}}

These values ​​can be incorporated into the URL or the supported headers so that the server knows which user is running each tool.

An example of dynamic headers would be:

headers:
  X-User-ID: "{{LIBRECHAT_USER_ID}}"
  X-User-Email: "{{LIBRECHAT_USER_EMAIL}}"
  X-User-Role: "{{LIBRECHAT_USER_ROLE}}"

This data can help enforce permissions, log transactions, or allocate resources. However, the MCP server must validate the information and not blindly rely on a header to protect sensitive actions.

LibreChat also has controls to determine who can use, create, share, or edit each MCP serverIn organizations, it is advisable to combine these permissions with the restrictions specific to the external service.

How to check the status of an MCP server

The MCP panel shows dynamic status indicators To facilitate diagnosis, a green gear indicates an active connection; an amber key indicates that authentication is required; and a red triangle warns of an error.

If a server stops responding, you can try Restart your connection from the interfaceThis avoids restarting the entire application when the problem only affects one server.

If the problem persists, check:

• The LibreChat and MCP server logs.
• That the specified command exists within the execution environment.
• Ensure the URL and port are accessible from LibreChat.
• That the API key or token remains valid.
• Ensure the server uses a compatible transport.
• That the selected model supports tool calls.
• That the user has permission to use the server.

The green indicator confirms that the connection has been established, but it does not guarantee that all tools will function correctly. A specific operation may still fail. insufficient permissions, incorrect parameters, or external service errors.

How to fix timeout errors

Servers handling complex queries may require more time than a standard chat response. In these cases, you can increase the response time. timeout for the operations and initTimeout for the start.

For example:

timeout: 120000
initTimeout: 30000

The values ​​are expressed in milliseconds. It is not advisable to increase them indiscriminately, as an excessively long time can cause a blocked operation to take a very long time to regain control.

If you use Nginx, Traefik, Cloudflare, or another proxy, also check its limits. Although LibreChat waits two minutes, the proxy can close the connection earlier and cause an incomplete response or a network error.

When using Streamable HTTP or SSE, also check that the proxy allows the connection to be maintained for the necessary time and does not improperly buffer transmitted responses.

Which MCP servers are worth installing

The choice depends on the task you want to perform. A file server can be useful for consulting local documentation, while one connected to a database allows for... Get updated information without copying logs to the chat.

Other common uses include:

• Consult repositories and manage development issues.
• Perform web searches or control a browser.
• Access databases such as PostgreSQL or ClickHouse.
• Connect business services using OAuth.
• Run automations and internal tools.

You don't need to install many servers from the beginning. It's preferable to start with one, check its permissions, and verify the actions it can perform. Then you can gradually expand the installation and assign tasks. different tools for each agent.

The integration of MCP transforms LibreChat into more than just an interface for chatting with models. Through local or remote servers, you can access up-to-date information and execute external functions from a single system.

The simplest setup involves adding a server from the MCP panel. For managed deployments, librechat.yaml It offers greater control over transport, wait times, authentication, and dynamic variables. In both cases, security must be a priority. Review the server, limit its permissions, and carefully authorize sensitive actions..