Cómo configurar servidores MCP en LibreChat y conectar herramientas externas

Si alguna vez te has preguntado cómo conseguir que una inteligencia artificial deje de limitarse a generar texto y pueda consultar archivos, utilizar servicios externos o ejecutar herramientas, LibreChat ofrece una solución mediante el Model Context Protocol.

El Model Context Protocol, conocido como MCP, es un estándar abierto que establece una forma común de conectar los modelos de lenguaje con fuentes de datos y herramientas. Suele compararse con el USB-C porque evita tener que desarrollar una integración completamente diferente para cada aplicación, modelo o servicio.

Gracias a este protocolo, LibreChat puede conectarse con sistemas de archivos, bases de datos, navegadores, repositorios de código, herramientas empresariales y APIs. El modelo no obtiene acceso ilimitado por el simple hecho de activar MCP: solamente puede utilizar las funciones que expone cada servidor y que el usuario o administrador haya autorizado.

Antes de instalar cualquier servidor, conviene revisar su procedencia. Un servidor MCP puede recibir información de las conversaciones y ejecutar acciones con los permisos que se le hayan concedido. Por este motivo, no deberías instalar servidores desconocidos ni proporcionarles credenciales sensibles sin comprobar antes su código, documentación y permisos.

Qué necesitas para utilizar servidores MCP en LibreChat

Para empezar necesitas tener una instalación actualizada de LibreChat y acceso a su configuración. Dependiendo del método elegido, también necesitarás permisos para editar el archivo librechat.yaml o autorización para crear servidores desde el panel MCP de la interfaz.

Los requisitos concretos dependen del servidor que quieras utilizar:

• Node.js o npx, cuando el servidor se distribuye como un paquete de JavaScript ejecutado mediante stdio.
• Python y sus dependencias, si el servidor está desarrollado en este lenguaje.
• Una URL accesible, cuando se trata de un servidor MCP remoto.
• Una clave API o autorización OAuth, si la herramienta se conecta con un servicio protegido.
• Acceso de red desde el contenedor, cuando LibreChat se ejecuta mediante Docker.

También debes utilizar un modelo compatible con llamadas a herramientas. Aunque el servidor esté conectado correctamente, un modelo sin soporte para herramientas puede no saber invocar sus funciones o producir resultados poco fiables.

Formas de añadir servidores MCP a LibreChat

LibreChat permite configurar los servidores MCP mediante dos procedimientos principales: desde la interfaz gráfica o editando manualmente el archivo librechat.yaml.

La interfaz es el método más cómodo para la mayoría de los usuarios. Desde el panel MCP de la barra lateral derecha puedes consultar los servidores existentes y utilizar el botón correspondiente para añadir uno nuevo. Este procedimiento permite introducir el nombre, el transporte, la URL y las credenciales sin modificar archivos ni reiniciar LibreChat.

La disponibilidad de esta opción puede depender de los permisos configurados por el administrador. LibreChat permite controlar por separado si un usuario puede utilizar, crear, compartir o publicar servidores MCP.

La configuración mediante librechat.yaml proporciona más control y resulta especialmente útil para administradores, despliegues reproducibles o servidores compartidos. En este caso, cualquier servidor nuevo o modificación introducida en el archivo requiere reiniciar LibreChat para inicializar la conexión.

Una configuración sencilla mediante stdio puede tener este aspecto:

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

El directorio indicado será accesible para el servidor. Por tanto, debes limitarlo a una ubicación concreta y evitar conceder acceso a todo el sistema de archivos si no resulta imprescindible.

También puedes buscar servidores en catálogos como Smithery. Estas plataformas facilitan encontrar proyectos disponibles y generar configuraciones compatibles. Sin embargo, aparecer en un catálogo no garantiza que un servidor sea seguro. Revisa siempre quién lo mantiene, qué permisos solicita y qué comandos ejecutará.

Cómo utilizar las herramientas MCP en un chat

Una vez establecida la conexión, LibreChat permite utilizar los servidores MCP directamente en una conversación. Primero debes seleccionar un modelo compatible con herramientas. Debajo del cuadro donde escribes el mensaje aparecerá el selector de servidores disponibles.

Al activar un servidor, sus herramientas pasan a estar disponibles para el modelo durante esa conversación. Puedes seleccionar varios servidores simultáneamente, aunque conviene evitar añadir funciones innecesarias porque un número excesivo de herramientas puede aumentar el contexto y dificultar que el modelo elija correctamente.

El administrador puede impedir que un servidor aparezca en este menú añadiendo la opción:

chatMenu: false

En ese caso, el servidor continuará disponible para los agentes, pero no aparecerá como herramienta seleccionable en los chats convencionales.

También debes revisar cada operación antes de aprobarla, especialmente cuando una herramienta pueda eliminar archivos, modificar bases de datos, enviar información o realizar acciones irreversibles.

Cómo añadir herramientas MCP a un agente

Los servidores MCP también pueden utilizarse con los Agentes de LibreChat. Desde el Agent Builder puedes abrir el apartado de herramientas, seleccionar un servidor y decidir cuáles de sus funciones estarán disponibles.

Este control individual resulta especialmente útil cuando un servidor expone muchas herramientas. Por ejemplo, puedes permitir que un agente consulte una base de datos, pero impedir que modifique o elimine registros.

LibreChat también admite la carga diferida de herramientas. Cuando una función se marca como diferida, no ocupa espacio en el contexto inicial del modelo. En su lugar, el agente utiliza un sistema de búsqueda para localizarla cuando resulta necesaria. Esta opción ayuda a reducir el consumo de contexto cuando se conectan servidores que ofrecen decenas de funciones.

La recomendación general consiste en aplicar el principio de mínimo privilegio: cada agente debería disponer solamente de las herramientas imprescindibles para realizar su función.

Tipos de transporte disponibles para MCP

LibreChat admite actualmente los transportes stdio, Streamable HTTP, SSE y WebSocket. La elección depende de dónde se ejecuta el servidor y de cómo debe comunicarse con LibreChat.

El transporte stdio inicia un proceso local y se comunica con él mediante la entrada y salida estándar. Es frecuente en servidores ejecutados con npx, Python u otros comandos locales. Resulta cómodo para instalaciones personales, pero puede complicarse en Docker o en entornos distribuidos.

Para servidores remotos nuevos, Streamable HTTP suele ser la alternativa más recomendable. Funciona mediante HTTP y se adapta mejor a servicios alojados, despliegues multiusuario y sistemas que necesitan escalar.

Una configuración remota básica podría ser:

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

El transporte SSE continúa siendo compatible y puede ser necesario para servidores antiguos que utilicen Server-Sent Events. WebSocket también está disponible para servicios que mantengan una comunicación persistente mediante direcciones ws:// o wss://.

Si se omite el campo type, LibreChat puede deducir el transporte a partir de la presencia de command o del formato de la URL. Aun así, declararlo explícitamente facilita la lectura y el diagnóstico de la configuración.

Parámetros importantes de librechat.yaml

Los parámetros necesarios cambian según el transporte utilizado. En los servidores stdio, los campos principales son command y args. El primero indica el programa que debe ejecutarse y el segundo contiene los argumentos enviados al proceso.

También puede utilizarse env para proporcionar variables de entorno:

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

En los transportes remotos, el parámetro esencial es url. También pueden añadirse encabezados HTTP, un proxy de salida, autenticación y variables dinámicas.

Otros parámetros importantes son:

• timeout: tiempo máximo permitido para ejecutar una operación.
• initTimeout: tiempo disponible para inicializar el servidor.
• startup: permite impedir que el servidor se conecte al iniciar LibreChat.
• chatMenu: controla si aparece en el selector del área de chat.
• requiresOAuth: indica si el servidor remoto necesita autenticación OAuth.
• headers: permite enviar encabezados personalizados en las conexiones remotas.

No debes guardar claves directamente en un archivo que vaya a subirse a GitHub. Para los secretos compartidos por toda la instalación, resulta más seguro utilizar variables de entorno como ${NOMBRE_VARIABLE}.

Cómo conectar servidores MCP cuando utilizas Docker

Cuando LibreChat funciona dentro de Docker, los comandos y direcciones se interpretan desde el contenedor y no desde el sistema anfitrión. Esta diferencia explica muchos de los errores de conexión.

Si configuras un servidor stdio que depende de Node.js, Python o una aplicación concreta, esas dependencias deben estar disponibles dentro del contenedor que ejecuta LibreChat. Tenerlas instaladas solamente en Windows o Linux anfitrión no significa que el contenedor pueda utilizarlas.

También debes tener cuidado con localhost. Dentro de un contenedor, esta dirección hace referencia al propio contenedor. Si el servidor MCP se ejecuta en el equipo anfitrión, puede ser necesario utilizar una dirección como:

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

La dirección exacta depende del sistema operativo y de la configuración de Docker. Otra opción consiste en ejecutar el servidor MCP dentro de su propio contenedor y conectar ambos servicios mediante la misma red de Docker Compose.

Antes de modificar LibreChat, comprueba que el endpoint responde desde el propio contenedor. Así podrás distinguir entre un problema del protocolo y un fallo de red, DNS, puerto o dependencias.

Autenticación OAuth para servidores MCP

LibreChat admite OAuth 2.0 para autenticar usuarios individualmente frente a servidores MCP remotos. Cuando detecta que un servidor necesita autorización, muestra al usuario la opción de iniciar el proceso desde el navegador.

La URL de retorno sigue este formato:

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

El nombre debe coincidir exactamente con la clave utilizada dentro de mcpServers o con el nombre asignado al servidor desde la interfaz. En una instalación local mediante Docker, la dirección base habitual puede ser:

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

Esta URL debe registrarse exactamente en el proveedor OAuth. Un protocolo incorrecto, un puerto diferente o una variación en el nombre provocarán normalmente errores de redirección o callback no válido.

Los tokens OAuth se almacenan por usuario, de manera que cada persona accede al servicio externo con su propia cuenta y sus propios permisos. Esto resulta especialmente importante en instalaciones compartidas.

Cómo utilizar claves diferentes para cada usuario

No todos los servicios ofrecen OAuth. Para los servidores que utilizan claves API u otras credenciales, LibreChat proporciona customUserVars.

Esta función permite solicitar un valor a cada usuario y utilizarlo posteriormente en un encabezado o variable de entorno. Por ejemplo:

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"

Cada usuario introduce su propia credencial desde la configuración de LibreChat. De esta forma, el administrador no necesita almacenar una única clave compartida para todos los miembros.

Estas variables también pueden emplearse en servidores stdio mediante el apartado env. No obstante, debes comprobar que la versión instalada de LibreChat sea reciente si observas que el servidor recibe literalmente el marcador en lugar del valor esperado.

Marcadores dinámicos y permisos por usuario

LibreChat permite enviar al servidor información dinámica relacionada con la persona que realiza la solicitud. Entre los marcadores disponibles se encuentran campos como:

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

Estos valores pueden incorporarse a la URL o a los encabezados admitidos para que el servidor sepa qué usuario está ejecutando cada herramienta.

Un ejemplo de encabezados dinámicos sería:

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

Estos datos pueden ayudar a aplicar permisos, registrar operaciones o separar recursos. Sin embargo, el servidor MCP debe validar la información y no confiar ciegamente en un encabezado para proteger acciones sensibles.

LibreChat también dispone de controles para determinar quién puede usar, crear, compartir o editar cada servidor MCP. En organizaciones resulta recomendable combinar estos permisos con las restricciones propias del servicio externo.

Cómo comprobar el estado de un servidor MCP

El panel MCP muestra indicadores de estado dinámicos para facilitar el diagnóstico. Un engranaje verde señala una conexión activa; una llave de color ámbar indica que hace falta autenticación; y un triángulo rojo avisa de un error.

Si un servidor deja de responder, puedes intentar reinicializar su conexión desde la interfaz. Esto evita reiniciar toda la aplicación cuando el problema afecta solamente a un servidor.

Cuando el fallo continúa, revisa:

• Los registros de LibreChat y del servidor MCP.
• Que el comando indicado exista dentro del entorno de ejecución.
• Que la URL y el puerto sean accesibles desde LibreChat.
• Que la clave API o el token continúen siendo válidos.
• Que el servidor utilice un transporte compatible.
• Que el modelo seleccionado admita llamadas a herramientas.
• Que el usuario tenga permiso para utilizar el servidor.

El indicador verde confirma que se ha establecido la conexión, pero no garantiza que todas las herramientas funcionen correctamente. Una operación concreta todavía puede fallar por permisos insuficientes, parámetros incorrectos o errores del servicio externo.

Cómo solucionar errores de tiempo de espera

Los servidores que realizan consultas complejas pueden necesitar más tiempo que una respuesta convencional del chat. En estos casos puedes aumentar timeout para las operaciones e initTimeout para el arranque.

Por ejemplo:

timeout: 120000
initTimeout: 30000

Los valores se expresan en milisegundos. No conviene aumentarlos indiscriminadamente, ya que un tiempo demasiado elevado puede hacer que una operación bloqueada tarde mucho en devolver el control.

Si utilizas Nginx, Traefik, Cloudflare u otro proxy, comprueba también sus límites. Aunque LibreChat espere dos minutos, el proxy puede cerrar la conexión antes y provocar una respuesta incompleta o un error de red.

Cuando utilices Streamable HTTP o SSE, revisa además que el proxy permita mantener la conexión durante el tiempo necesario y no almacene indebidamente en búfer las respuestas transmitidas.

Qué servidores MCP merece la pena instalar

La elección depende del trabajo que quieras realizar. Un servidor de archivos puede resultar útil para consultar documentación local, mientras que uno conectado a una base de datos permite obtener información actualizada sin copiar los registros al chat.

Otros usos habituales incluyen:

• Consultar repositorios y gestionar incidencias de desarrollo.
• Realizar búsquedas web o controlar un navegador.
• Acceder a bases de datos como PostgreSQL o ClickHouse.
• Conectar servicios empresariales mediante OAuth.
• Ejecutar automatizaciones y herramientas internas.

No necesitas instalar muchos servidores desde el principio. Es preferible comenzar con uno, comprobar sus permisos y verificar las acciones que puede realizar. Después puedes ampliar la instalación gradualmente y asignar herramientas diferentes a cada agente.

La integración de MCP convierte LibreChat en algo más que una interfaz para conversar con modelos. Mediante servidores locales o remotos, puede consultar información actualizada y ejecutar funciones externas desde un sistema común.

La configuración más sencilla consiste en añadir un servidor desde el panel MCP. Para despliegues administrados, librechat.yaml ofrece mayor control sobre transportes, tiempos de espera, autenticación y variables dinámicas. En ambos casos, la seguridad debe ser prioritaria: revisa el servidor, limita sus permisos y autoriza cuidadosamente las acciones sensibles.