Cómo conectar LibreChat con el Model Context Protocol (MCP)

Si alguna vez has sentido que tu inteligencia artificial está encerrada en una burbuja y no puede interactuar con servicios externos, el Model Context Protocol (MCP) puede ayudarte a superar esa limitación. Este protocolo abierto suele compararse con el USB-C de la inteligencia artificial porque establece una interfaz común para conectar aplicaciones de IA con herramientas, fuentes de datos y servicios especializados.

LibreChat aprovecha este estándar para ampliar las capacidades de los modelos disponibles en su interfaz. Mediante servidores MCP, un modelo compatible con el uso de herramientas puede consultar archivos, interactuar con APIs empresariales, automatizar un navegador o ejecutar acciones en otros sistemas.

En esta guía veremos cómo conectar LibreChat con servidores MCP mediante el archivo librechat.yaml o desde la interfaz, cómo utilizar sus herramientas en conversaciones y agentes, y qué debes tener en cuenta al configurar OAuth, Docker y los tiempos de espera.

Qué necesitas para utilizar MCP en LibreChat

Antes de configurar un servidor, conviene aclarar que MCP no convierte automáticamente cualquier modelo en un agente capaz de ejecutar acciones. Para utilizar las herramientas del servidor necesitas seleccionar un modelo compatible con tool calling y un endpoint de LibreChat que permita esta función.

El servidor MCP es el componente que publica las herramientas. LibreChat actúa como cliente: descubre esas herramientas, muestra sus parámetros al modelo y transmite las llamadas cuando el modelo decide utilizarlas.

Algunas herramientas solo consultan información, mientras que otras pueden modificar archivos, enviar mensajes o ejecutar operaciones externas. Por eso debes conectar únicamente servidores confiables y limitar sus permisos al mínimo necesario.

Formas de añadir servidores MCP en LibreChat

LibreChat permite incorporar servidores MCP mediante tres métodos: editando el archivo librechat.yaml, utilizando el panel de configuración de la interfaz o generando la configuración desde Smithery.

Configurar un servidor en librechat.yaml

El archivo librechat.yaml proporciona el mayor control. En él puedes definir servidores locales basados en STDIO, conexiones remotas, encabezados HTTP, variables de entorno, credenciales aportadas por los usuarios y tiempos de espera.

Este ejemplo declara un servidor remoto mediante Streamable HTTP:

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

El valor initTimeout establece cuánto tiempo puede tardar la conexión inicial. Por su parte, timeout determina el tiempo máximo concedido a las operaciones del servidor.

También puedes iniciar un servidor local mediante un comando:

mcpServers:
  documentos:
    command: npx
    args:
      - "-y"
      - "@modelcontextprotocol/server-filesystem"
      - "/documentos"

Después de añadir o modificar un servidor en librechat.yaml, debes reiniciar LibreChat para que cargue la nueva configuración. Si utilizas Docker Compose, normalmente puedes hacerlo mediante:

docker compose restart

Si el archivo no estaba montado correctamente o has cambiado la configuración del propio contenedor, puede ser necesario recrearlo:

docker compose up -d --force-recreate

Añadir un servidor desde la interfaz

Las versiones actuales de LibreChat permiten crear servidores remotos desde el panel MCP Settings situado en la barra lateral derecha. Pulsa el botón de añadir e introduce el nombre, la descripción, la URL, el transporte y el método de autenticación.

Los servidores creados de esta forma se guardan sin necesidad de editar archivos ni reiniciar LibreChat. Además, quedan disponibles tanto en las conversaciones compatibles como en el Agent Builder.

Esta opción depende de los permisos de acceso configurados por el administrador. Un usuario necesita autorización para crear servidores MCP y, si corresponde, para compartirlos con otros usuarios o grupos.

La configuración desde la interfaz está orientada principalmente a servidores MCP remotos accesibles mediante una URL. Si necesitas ejecutar comandos STDIO, utilizar variables de entorno del servidor o aplicar una configuración avanzada, es preferible declarar el servidor en librechat.yaml.

Instalar servidores mediante Smithery

Smithery es un catálogo desde el que puedes localizar servidores MCP y generar instrucciones para diferentes clientes. Después de elegir un servidor, abre la sección de conexión automática, selecciona LibreChat y revisa el comando proporcionado.

Este procedimiento incorpora la configuración correspondiente en librechat.yaml. Por tanto, debes reiniciar LibreChat después de la instalación para inicializar la conexión.

No ejecutes automáticamente cualquier comando publicado en un catálogo comunitario. Antes de instalarlo, revisa el proyecto, los permisos solicitados, las variables requeridas y las acciones que podrán ejecutar sus herramientas.

Cómo utilizar servidores MCP en una conversación

LibreChat puede mostrar los servidores configurados debajo del cuadro de texto cuando utilizas un endpoint convencional, como OpenAI, Anthropic, Google o Amazon Bedrock. Primero debes seleccionar un modelo compatible con herramientas.

Desde el menú MCP puedes activar uno o varios servidores. Las herramientas de los servidores seleccionados quedarán disponibles para el modelo durante la conversación.

No conviene habilitar todas las herramientas indiscriminadamente. Un catálogo demasiado grande puede dificultar que el modelo elija la función adecuada, aumentar el contexto enviado y provocar llamadas innecesarias.

Si un servidor debe estar disponible para los agentes pero no en el menú del chat, puedes ocultarlo mediante:

mcpServers:
  herramientas-internas:
    type: streamable-http
    url: "https://mcp.example.com/mcp"
    chatMenu: false

Cómo añadir herramientas MCP a un agente

Para utilizar MCP dentro de un agente, abre el Agent Builder, entra en la sección de herramientas y selecciona MCP. Cada servidor aparece como una entrada que puede desplegarse para mostrar sus funciones.

LibreChat permite habilitar o deshabilitar herramientas individuales. Esta selección granular resulta especialmente útil cuando un servidor publica muchas operaciones y el agente solo necesita unas pocas.

Por ejemplo, un servidor empresarial podría permitir consultar clientes, modificar facturas y eliminar registros. Un agente dedicado al soporte probablemente solo necesite la herramienta de consulta. Excluir el resto reduce el riesgo de acciones accidentales y facilita que el modelo interprete correctamente su función.

Los nombres y las descripciones proporcionados por el servidor también influyen en el resultado. Cada herramienta debería explicar claramente qué hace, qué parámetros acepta y en qué situaciones debe utilizarse.

Cómo configurar OAuth en un servidor MCP

LibreChat admite servidores MCP protegidos mediante OAuth 2.0. El flujo Authorization Code con PKCE es la opción recomendada cuando el proveedor lo admite. También puede utilizar descubrimiento de clientes, renovación automática mediante refresh tokens y detección de endpoints.

Cuando LibreChat detecta que el servidor requiere autorización, muestra un indicador en la interfaz. El usuario inicia el proceso, completa la autenticación en el proveedor y regresa a LibreChat mediante una URL de callback.

La dirección debe seguir exactamente este formato:

${DOMAIN_SERVER}/api/mcp/<nombre-del-servidor>/oauth/callback

El nombre debe coincidir con la clave declarada dentro de mcpServers o con el nombre asignado desde MCP Settings. Por ejemplo:

https://chat.example.com/api/mcp/salesforce/oauth/callback

En una instalación local mediante Docker, la base suele ser:

http://localhost:3080

La URL completa debe registrarse sin cambios en el proveedor OAuth. Rutas genéricas como /api/oauth/callback no sirven para las conexiones MCP.

LibreChat almacena los tokens de forma cifrada y puede renovarlos automáticamente cuando el proveedor entrega un refresh token. Cada usuario mantiene su propia sesión OAuth, lo que evita compartir una única autorización entre todos los miembros de una instancia.

Cómo permitir que cada usuario proporcione su API key

Si el servidor no utiliza OAuth, puedes emplear customUserVars para que cada usuario introduzca sus propias credenciales. De esta forma, la clave no queda escrita directamente en el archivo de configuración.

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

El valor aportado se guarda asociado al usuario y al servidor correspondiente. Después de introducirlo, el usuario puede reinicializar la conexión desde el panel MCP sin reiniciar toda la aplicación.

Al crear un servidor desde la interfaz también puedes seleccionar la opción para que el usuario proporcione su clave. LibreChat genera internamente una variable denominada MCP_API_KEY y prepara el encabezado elegido.

Los servidores creados desde la interfaz solo pueden resolver estas variables de usuario. Por motivos de seguridad, no pueden acceder directamente a variables de entorno del servidor ni a campos privados de otros usuarios. Si necesitas esas funciones, configura el servidor mediante YAML.

Tipos de transporte admitidos por LibreChat

LibreChat admite cuatro tipos principales de transporte MCP:

Transporte	Uso recomendado	Consideraciones
STDIO	Servidores locales iniciados mediante comandos	El ejecutable y sus dependencias deben estar disponibles en el mismo entorno que LibreChat.
Streamable HTTP	Servidores remotos y despliegues actuales	Es el transporte HTTP moderno recomendado para nuevas integraciones remotas.
SSE	Compatibilidad con servidores remotos antiguos	Continúa siendo compatible, aunque muchas implementaciones nuevas utilizan Streamable HTTP.
WebSocket	Servidores que mantienen una conexión bidireccional	Debe seleccionarse únicamente cuando el servidor publique este transporte.

Streamable HTTP no debe describirse necesariamente como un sistema sin estado. El comportamiento de las sesiones depende de la implementación concreta del servidor. Su principal ventaja es que forma parte del transporte HTTP actual de MCP y resulta adecuado para servicios remotos.

Cómo conectar servidores MCP cuando LibreChat utiliza Docker

Los servidores STDIO se ejecutan como procesos secundarios de LibreChat. Si la aplicación funciona dentro de Docker, comandos como npx, uvx o el ejecutable del servidor deben estar instalados dentro del contenedor, no solamente en el sistema anfitrión.

También debes montar dentro del contenedor cualquier carpeta que necesite el servidor. Un servidor de archivos no podrá acceder automáticamente a todos los directorios del equipo anfitrión.

Para despliegues multiusuario puede resultar más sencillo ejecutar los servidores MCP como servicios independientes y conectarlos mediante Streamable HTTP. Esta arquitectura permite actualizar y aislar cada servicio por separado, aunque requiere proteger la red y la autenticación entre contenedores.

Recuerda que localhost dentro del contenedor de LibreChat apunta al propio contenedor. Si el servidor MCP está definido como otro servicio de Docker Compose, debes utilizar su nombre de servicio:

mcpServers:
  herramientas:
    type: streamable-http
    url: "http://servidor-mcp:8000/mcp"

Ambos servicios deben pertenecer a una red de Docker común. Evita publicar el puerto del servidor MCP en Internet si solo necesita recibir conexiones internas de LibreChat.

Cómo ajustar los tiempos de espera correctamente

LibreChat diferencia entre el tiempo disponible para completar OAuth y los tiempos de ejecución del servidor MCP.

Estas variables controlan únicamente el proceso de autorización:

MCP_OAUTH_HANDLING_TIMEOUT=600000
MCP_OAUTH_FLOW_TTL=900000

De forma predeterminada, LibreChat concede aproximadamente diez minutos para completar OAuth y mantiene el estado del flujo durante quince minutos. Aumentar estos valores no evita que una herramienta lenta finalice por timeout.

Para la inicialización y ejecución de herramientas debes utilizar los campos del servidor:

mcpServers:
  procesador:
    type: streamable-http
    url: "https://mcp.example.com/mcp"
    initTimeout: 30000
    timeout: 120000

• initTimeout controla cuánto puede tardar el servidor en inicializarse.
• timeout controla cuánto puede durar una operación o llamada a una herramienta.

Si la conexión continúa cerrándose antes de tiempo, revisa también los límites del proxy inverso, balanceador o plataforma de alojamiento. Nginx, Traefik o un proveedor en la nube pueden aplicar sus propios tiempos máximos.

Cómo proteger los servidores MCP de LibreChat

Una herramienta MCP puede tener acceso a información sensible o realizar acciones con consecuencias reales. Antes de habilitarla, aplica estas recomendaciones:

• Conecta únicamente servidores procedentes de desarrolladores o repositorios confiables.
• Revisa el código y los comandos antes de instalar paquetes comunitarios.
• Concede acceso solo a las carpetas, APIs y operaciones necesarias.
• Utiliza OAuth o credenciales individuales en lugar de compartir una clave global.
• Deshabilita las herramientas que el agente no necesite.
• Evita exponer servidores MCP internos directamente a Internet.
• Protege LibreChat mediante HTTPS y configura correctamente sus permisos.
• Revisa los registros para detectar llamadas inesperadas o errores de autenticación.
• Solicita confirmación antes de ejecutar acciones destructivas o irreversibles.

También debes tener en cuenta los ataques de inyección de instrucciones. Un documento, una página web o una respuesta externa podría contener texto diseñado para manipular al agente. Las herramientas con capacidad para escribir archivos, ejecutar comandos o modificar datos requieren límites especialmente estrictos.

LibreChat incorpora protecciones contra solicitudes dirigidas a direcciones internas. Si necesitas conectar un servidor situado en una red privada, tendrás que autorizar explícitamente su dominio o dirección mediante mcpSettings. Limita esa excepción al host y puerto necesarios, en lugar de permitir rangos completos sin justificación.

Errores frecuentes al conectar LibreChat con MCP

El servidor no aparece después de editar librechat.yaml

Comprueba la indentación del YAML y reinicia LibreChat. En Docker, verifica además que el archivo correcto esté montado dentro del contenedor.

El comando npx o uvx no se encuentra

El ejecutable debe estar instalado en el entorno donde se ejecuta LibreChat. Si utilizas Docker, instalarlo únicamente en el anfitrión no es suficiente.

Una dirección con localhost no funciona

Dentro de Docker, localhost hace referencia al contenedor actual. Utiliza el nombre del servicio de Docker, una dirección accesible de la red interna o la configuración correspondiente para alcanzar el anfitrión.

El servidor no aparece en el chat

Selecciona un endpoint que no sea un agente y un modelo compatible con herramientas. Comprueba también que el servidor no tenga configurado chatMenu: false.

OAuth devuelve un error de redirección

Verifica que la URL registrada en el proveedor coincida exactamente con el dominio de LibreChat, la ruta MCP y el nombre del servidor.

La herramienta termina antes de completar la operación

Aumenta el campo timeout del servidor y revisa los límites del proxy. Las variables MCP_OAUTH_FLOW_TTL y MCP_OAUTH_HANDLING_TIMEOUT no controlan la duración de las herramientas.

La conexión a un servidor interno está bloqueada

LibreChat puede bloquear destinos privados como protección frente a SSRF. Autoriza expresamente el dominio o la dirección necesaria en mcpSettings, sin abrir acceso a más destinos de los imprescindibles.

Conectar LibreChat con MCP permite incorporar herramientas externas a conversaciones y agentes mediante una interfaz estandarizada. La configuración puede realizarse desde librechat.yaml, desde el panel MCP Settings o con ayuda de catálogos como Smithery.

Para conseguir una integración fiable, elige el transporte adecuado, configura correctamente las credenciales, utiliza modelos compatibles con herramientas y diferencia los tiempos de espera de OAuth de los correspondientes a la ejecución. En entornos de producción, limita las funciones disponibles y trata cada servidor MCP como un componente con acceso potencial a información y acciones sensibles.