Estructura del objeto de servidores MCP

Ejemplo

# Example MCP Servers Object Structure
mcpServers:
  everything:
    # type: sse # type can optionally be omitted
    url: http://localhost:3001/sse
  googlesheets:
    type: sse
    url: https://mcp.composio.dev/googlesheets/some-endpoint
    requiresOAuth: true
    headers:
      X-User-ID: '{{LIBRECHAT_USER_ID}}'
      X-API-Key: '${SOME_API_KEY}'
    serverInstructions: true # Use server-provided instructions
  puppeteer:
    type: stdio
    command: npx
    args:
      - -y
      - '@modelcontextprotocol/server-puppeteer'
    serverInstructions: 'Do not access any local files or local/internal IP addresses'
  filesystem:
    # type: stdio
    command: npx
    args:
      - -y
      - '@modelcontextprotocol/server-filesystem'
      - /home/user/LibreChat/
    iconPath: /home/user/LibreChat/client/public/assets/logo.svg
    # The “wrench” icon shows up if no icon is provided as it is the default rendering.
  mcp-obsidian:
    command: npx
    args:
      - -y
      - 'mcp-obsidian'
      - /path/to/obsidian/vault
  streamable-http-server:
    type: streamable-http
    url: https://example.com/api/
    proxy: '${MCP_PROXY_URL}'
  per-user-credentials-example:
    type: streamable-http
    url: 'https://example.com/api/'
    headers:
      X-Auth-Token: '{{MY_SERVICE_API_KEY}}'
    customUserVars:
      MY_SERVICE_API_KEY:
        title: 'My Service API Key'
        description: "Enter your personal API key for the service. You can generate one at <a href='https://myservice.example.com/developer/keys' target='_blank'>Service Developer Portal</a>."
        sensitive: true
      MY_SERVICE_PROJECT:
        title: 'Project ID'
        description: 'Enter the project ID used by this service.'
        sensitive: false
  oauth-example:
    type: streamable-http
    url: https://api.example.com/mcp/
    oauth:
      authorization_url: https://example.com/oauth/authorize
      token_url: https://example.com/oauth/token
      client_id: your_client_id
      client_secret: your_client_secret
      redirect_uri: http://localhost:3080/api/mcp/oauth-example/oauth/callback
      scope: 'read execute'
  obo-example:
    type: streamable-http
    url: https://api.example.com/mcp/
    obo:
      scopes: 'api://mcp-server-id/Mcp.Tools.ReadWrite'

<serverName>

Clave:

Subclaves

title

• Tipo: Cadena (Opcional)
• Descripción: Nombre para mostrar personalizado para el servidor MCP en la interfaz de usuario. Si no se especifica, se utiliza el nombre de la clave del servidor.
• Ejemplo:

  my-server:
    title: 'File System Access'
    command: npx
    args: ['-y', '@modelcontextprotocol/server-filesystem']

description

• Tipo: Cadena (Opcional)
• Descripción: Descripción del servidor MCP, que se muestra en la interfaz de usuario para ayudar a los usuarios a comprender su propósito y capacidades.
• Ejemplo:

  my-server:
    title: 'File System Access'
    description: 'Provides read/write access to local files and directories'
    command: npx
    args: ['-y', '@modelcontextprotocol/server-filesystem']

type

• Tipo: String
• Descripción: Especifica el tipo de conexión al servidor MCP. Las opciones válidas son "stdio", "websocket", "streamable-http" o "sse".
• Valor predeterminado: Determinado según la presencia y el formato de url o command.

command

• Tipo: String
• Descripción: (Para el tipo stdio) El comando o ejecutable a ejecutar para iniciar el servidor MCP.

args

• Tipo: Matriz de cadenas
• Descripción: (Para el tipo stdio) Argumentos de línea de comandos para pasar al command.

url

• Tipo: String
• Descripción: (Para el tipo websocket, streamable-http o sse) La URL para conectarse al servidor MCP. Admite marcadores de posición dinámicos para campos de usuario ({{LIBRECHAT_USER_*}}) y sustitución de variables de entorno (${ENV_VAR}).
• Notas:
  • Para el tipo sse, la URL debe comenzar con http:// o https://.
  • Para el tipo streamable-http, la URL debe comenzar con http:// o https://.
  • Para el tipo websocket, la URL debe comenzar con ws:// o wss://.

proxy

• Tipo: String (Opcional, para los tipos sse y streamable-http)
• Descripción: URL del proxy de salida para este servidor MCP remoto. El valor puede hacer referencia a variables de entorno con ${ENV_VAR}.
• Protocolos compatibles: http://, https://, socks:// y socks5://
• Nota de seguridad: proxy está controlado por el administrador. Resuelve variables de entorno, pero no resuelve marcadores de posición controlados por el usuario como {{LIBRECHAT_USER_ID}} o customUserVars.
• Ejemplo:

  mcpServers:
    remote-api:
      type: streamable-http
      url: https://api.example.com/mcp
      proxy: '${MCP_PROXY_URL}'

headers

• Tipo: Objeto (Opcional, para los tipos sse y streamable-http)
• Descripción: Encabezados personalizados para enviar con la solicitud. Admite varios tipos de marcadores de posición para la sustitución dinámica de valores.
• Soporte para marcadores de posición (Placeholder):
  • {{LIBRECHAT_USER_ID}}: Se reemplazará con el ID del usuario actual, permitiendo el soporte multiusuario.
  • {{LIBRECHAT_USER_*}}: Marcadores de posición dinámicos para campos de usuario. Reemplace * con la versión en MAYÚSCULAS de cualquier campo permitido.
  • {{LIBRECHAT_OPENID_*}}: Marcadores de posición de token/sesión de OpenID para servidores definidos en YAML.
  • {{LIBRECHAT_GRAPH_*}}: marcadores de posición de token de Microsoft Graph para servidores definidos en YAML.
  • {{LIBRECHAT_BODY_*}}: Marcadores de posición del cuerpo de la solicitud para servidores definidos en YAML, tales como el conversationId, parentMessageId o messageId actuales.
  • {{CUSTOM_VARIABLE_NAME}}: Reemplazado por el valor proporcionado por el usuario para una variable definida en customUserVars (por ejemplo, {{MY_API_KEY}}).
  • ${ENV_VAR}: Se reemplazará con el valor de la variable de entorno {{ENV_VAR}}.

Marcadores de posición de campo de usuario disponibles:

Nota: Los campos faltantes serán reemplazados por cadenas vacías.

Los marcadores de posición {{LIBRECHAT_BODY_*}} tienen un ámbito de solicitud (request-scoped). LibreChat crea la conexión MCP para la ejecución activa, la reutiliza en las llamadas a herramientas durante esa ejecución y la cierra cuando finaliza la solicitud. Los servidores con ámbito de solicitud se excluyen de la caché persistente de herramientas para que los encabezados y las URLs específicos de la solicitud no se reutilicen fuera de la ejecución activa. Los marcadores de posición {{LIBRECHAT_USER_*}}, {{LIBRECHAT_OPENID_*}} y {{LIBRECHAT_GRAPH_*}} siguen haciendo que el servidor tenga un ámbito de usuario, pero los transportes HTTP actualizan los encabezados resueltos antes de cada llamada a herramienta sin forzar una reconexión por sí mismos.

• Ejemplo:

  headers:
    X-User-ID: '{{LIBRECHAT_USER_ID}}'
    X-User-Email: '{{LIBRECHAT_USER_EMAIL}}'
    X-User-Role: '{{LIBRECHAT_USER_ROLE}}'
    X-API-Key: '${SOME_API_KEY}'
    Authorization: 'Bearer ${SOME_AUTH_TOKEN}'

apiKey

• Tipo: Objeto (Opcional, para los tipos sse y streamable-http)

• Descripción: Configuración de autenticación mediante clave API para el servidor MCP. Proporciona una forma estructurada de configurar la autenticación basada en claves API.

• Sub-claves:

  • source: String - De dónde proviene la clave de API. Opciones:
    • "admin": La clave API está configurada por el administrador (en variables de entorno o configuración)
    • "user": La clave de API es proporcionada por el usuario a través de la interfaz de usuario
  • authorization_type: String - Cómo se envía la clave de API en las solicitudes. Opciones:
    • "bearer": Enviado como Authorization: Bearer <key>
    • "basic": Enviado como Authorization: Basic <key>
    • "custom": Enviado en un encabezado personalizado (requiere custom_header)
  • custom_header: String - (Requerido cuando authorization_type es "custom") El nombre del encabezado a utilizar para la clave de API

• Ejemplo:

  # Admin-provided API key with Bearer auth
  my-server:
    type: streamable-http
    url: https://api.example.com/mcp
    apiKey:
      source: 'admin'
      authorization_type: 'bearer'
  
  # User-provided API key with custom header
  another-server:
    type: sse
    url: https://api.example.com/sse
    apiKey:
      source: 'user'
      authorization_type: 'custom'
      custom_header: 'X-API-Key'

iconPath

• Tipo: Cadena (Opcional)
• Descripción: Define el icono de visualización de la herramienta que se muestra en el cuadro de diálogo de selección de herramientas.

chatMenu

• Tipo: Booleano (Opcional)
• Descripción: Cuando se establece en false, excluye el servidor MCP del menú desplegable del área de chat (MCPSelect) para un acceso rápido y sencillo.
• Valor predeterminado: true (El servidor MCP se incluirá en el menú desplegable del área de chat)

serverInstructions

• Tipo: Booleano o Cadena (Opcional)

• Descripción: Controla cómo se inyectan las instrucciones del servidor MCP en el contexto del agente. Las instrucciones del servidor proporcionan una guía de uso de alto nivel para todo el servidor MCP, complementando las descripciones de las herramientas individuales.

• Opciones:

  • undefined (predeterminado): No se incluyen instrucciones
  • true: Utilizar las instrucciones proporcionadas por el servidor (si están disponibles); ideal para servidores bien documentados con una guía exhaustiva
  • false: Deshabilita explícitamente las instrucciones; útil para ahorrar tokens de contexto o cuando las herramientas son autoexplicativas
  • string: Utiliza instrucciones personalizadas (anulan las proporcionadas por el servidor); es ideal para flujos de trabajo específicos de la aplicación o cuando las instrucciones del servidor son insuficientes.

• Valor predeterminado: undefined (no se incluyen instrucciones)

• Notas:

  • Las instrucciones se inyectan automáticamente cuando serverInstructions está configurado y las herramientas del servidor están disponibles para el agente.
  • Varios servidores pueden contribuir cada uno con instrucciones al contexto del agente

• Ejemplo:

  # Use server-provided instructions
  serverInstructions: true
  
  # Use custom instructions
  serverInstructions: |
    When using this filesystem server:
    1. Always use absolute paths for file operations
    2. Check file permissions before attempting write operations
  
  # Explicitly disable instructions
  serverInstructions: false

env

• Tipo: Objeto (Opcional, solo para el tipo stdio)
• Descripción: Variables de entorno a utilizar al iniciar el proceso.
• Soporte para marcadores de posición (Placeholder):
  • {{LIBRECHAT_USER_ID}}: Reemplazado con el ID del usuario actual.
  • {{LIBRECHAT_USER_*}}: Marcadores de posición dinámicos para campos de usuario (por ejemplo, {{LIBRECHAT_USER_EMAIL}}).
  • {{CUSTOM_VARIABLE_NAME}}: Reemplazado por el valor proporcionado por el usuario para una variable definida en customUserVars (por ejemplo, {{MY_API_KEY}}).
  • ${ENV_VAR}: Reemplazado con el valor de la variable de entorno del lado del servidor {{ENV_VAR}}.

timeout

• Tipo: Entero (Opcional)
• Descripción: Tiempo de espera en milisegundos para las solicitudes del servidor MCP. Debe ser un número entero no negativo.
• Valor predeterminado: 30000 (30 segundos)

initTimeout

• Tipo: Entero (Opcional)
• Descripción: Tiempo de espera en milisegundos para la inicialización del servidor MCP. Debe ser un número entero no negativo.
• Valor predeterminado: 10000 (10 segundos)

requiresOAuth

• Tipo: Booleano (Opcional, solo para transportes remotos: sse, streamable-http, websocket)
• Descripción: Si este servidor requiere autenticación OAuth. Si no se especifica, se detectará automáticamente durante el inicio del servidor. Aunque es opcional, es mejor establecer este valor explícitamente si sabe si el servidor requiere OAuth o no.
• Valor predeterminado: Detectado automáticamente si no se especifica
• Notas:
  • Aplicable a transportes remotos (basados en URL): sse, streamable-http y websocket. No tiene efecto en servidores stdio, los cuales no tienen una URL contra la cual autenticarse.
  • La detección automática ocurre durante el inicio del servidor, lo cual puede añadir tiempo de inicialización
  • La configuración explícita mejora el rendimiento de inicio al omitir la detección
  • Establezca requiresOAuth: false para servidores protegidos únicamente por un encabezado Authorization estático (por ejemplo, una clave API Bearer). La detección automática sondea el servidor sin sus encabezados configurados, por lo que un servidor que responde con un desafío 401 con WWW-Authenticate: Bearer puede ser clasificado erróneamente como protegido por OAuth; este indicador omite ese sondeo y permite que su encabezado estático autentique la conexión normalmente.
  • Funciona con las variables de entorno de OAuth para MCP (MCP_OAUTH_ON_AUTH_ERROR, MCP_OAUTH_DETECTION_TIMEOUT, MCP_OAUTH_HANDLING_TIMEOUT, MCP_OAUTH_FLOW_TTL) para una gestión de conexiones mejorada.

stderr

• Tipo: Cadena o Entero (Opcional, solo tipo stdio)
• Descripción: Cómo manejar stderr del proceso hijo. Esto coincide con la semántica de child_process.spawn de Node. Valores de cadena válidos: "pipe", "ignore", "inherit". Alternativamente, se puede usar un número entero no negativo como descriptor de archivo.
• Valor predeterminado: "inherit" (los mensajes a stderr se imprimirán en el stderr del proceso padre).

customUserVars

• Tipo: Objeto (Opcional)
• Descripción: Define variables personalizadas que los usuarios pueden configurar para este servidor MCP. Esto permite a los administradores especificar variables (por ejemplo, claves API, URLs) que cada usuario debe configurar individualmente. Estos valores proporcionados por el usuario pueden utilizarse posteriormente en la configuración de headers o env. Los servidores con customUserVars se excluyen automáticamente de las conexiones a nivel de aplicación, lo que garantiza que las credenciales por usuario se resuelvan siempre en tiempo de ejecución.
• Estructura:
  • El objeto customUserVars contiene claves, donde cada clave representa un nombre de variable (por ejemplo, MY_API_KEY). Este nombre se utilizará en marcadores de posición como {{MY_API_KEY}}.
  • Cada nombre de variable es un objeto con las siguientes subclaves:
    • title: String (Requerido) - Un título fácil de usar para la variable, que se muestra en la interfaz de usuario de configuración.
    • description: String (Optional) - A description or instructions for the variable, also displayed in the UI to guide the user. HTML can be used in this field (e.g., to create a link: <a href="https://example.com" target="_blank">More info</a>).
    • sensitive: Booleano (Opcional) - Controla si el valor se trata como un secreto y se oculta en la UI. Por defecto, se oculta/trata como secreto cuando se omite; establézcalo en false para campos que no sean secretos, como IDs de proyecto o URLs base.
• Uso en headers y env:
  • Una vez definidas bajo customUserVars, estas variables pueden ser referenciadas en las secciones headers (para los tipos sse y streamable-http) o env (para el tipo stdio) utilizando la sintaxis {{VARIABLE_NAME}}.
  • Los usuarios proporcionan estos valores a través de la interfaz de usuario. Se puede acceder a estos ajustes de dos maneras:
    • Desde la entrada de chat del asistente: Al seleccionar herramientas MCP para un asistente, aparecerá un icono de configuración junto a los servidores MCP configurables en el menú desplegable de selección de herramientas. Al hacer clic en este icono, se abre un cuadro de diálogo para gestionar las credenciales de ese servidor.
    • Desde el panel de configuración: Una sección dedicada de "MCP Settings" en el panel derecho enumera todos los servidores MCP con variables personalizadas definibles. Los usuarios pueden hacer clic en un servidor para abrir el cuadro de diálogo de configuración y establecer o actualizar sus credenciales para ese servidor MCP específico.
  • Estos valores proporcionados por el usuario se almacenan de forma segura, asociados con el usuario individual y el servidor MCP específico, y se sustituyen en tiempo de ejecución.
• Ejemplo:

  customUserVars:
    MY_SERVICE_API_KEY:
      title: 'My Service API Key'
      description: "Your personal API access key for My Service. Find it at <a href='https://myservice.example.com/settings/api' target='_blank'>My Service API Settings</a>."
      sensitive: true
    SOME_OTHER_VAR:
      title: 'Some Other Variable'
      description: 'The specific value for some other configuration (e.g., a specific path or identifier).'
      sensitive: false

  Uso en headers:

  headers:
    X-Auth-Token: '{{MY_SERVICE_API_KEY}}'
    X-Some-Other-Config: '{{SOME_OTHER_VAR}}'

  Usage in env (for stdio type):

  env:
    API_KEY: '{{MY_SERVICE_API_KEY}}'

obo

• Tipo: Objeto (Opcional, solo para los tipos sse y streamable-http)
• Descripción: Configura el intercambio de tokens OAuth 2.0 On-Behalf-Of para un servidor MCP. LibreChat intercambia el token de acceso OpenID del usuario que ha iniciado sesión por un token delegado de nivel inferior con los alcances configurados, y luego reenvía ese token al servidor MCP como una cabecera Authorization: Bearer ....
• Subclaves requeridas:
  • scopes: String - Scopes no vacíos solicitados para el intercambio de tokens descendente.
• Validación:
  • obo solo es válido para servidores MCP de tipo sse y streamable-http.
  • obo es rechazado para servidores stdio y websocket.
  • Los usuarios necesitan el permiso de rol MCP_SERVERS.CONFIGURE_OBO para configurar este campo. Asígnelo con interface.mcpServers.configureObo o adminístrelo desde el panel de administración.
• Requisitos previos:
  • La autenticación OpenID debe configurarse con tokens de acceso reutilizables.
  • Tu proveedor de identidad y la aplicación downstream deben permitir el ámbito delegado solicitado.
• Ejemplo:

  mcpServers:
    enterprise-tools:
      type: streamable-http
      url: https://api.example.com/mcp/
      obo:
        scopes: 'api://mcp-server-id/Mcp.Tools.ReadWrite'

Consulte OpenID Connect Token Reuse y SharePoint Integration para obtener información relacionada sobre la reutilización de tokens y la configuración de tokens delegados.

oauth

• Tipo: Objeto (Opcional)
• Descripción: Configuración de OAuth2 para la autenticación con el servidor MCP. Cuando se configura, se solicitará a los usuarios que se autentiquen mediante el flujo OAuth antes de que se pueda utilizar el servidor MCP. Si no se proporciona un client id ni un client secret, se utilizará el Registro Dinámico de Clientes (DCR).
• Subclaves requeridas:
  • authorization_url: String - La URL del endpoint de autorización OAuth
  • token_url: String - La URL del endpoint de token OAuth
  • client_id: String - Identificador de cliente OAuth
  • client_secret: String - Secreto de cliente OAuth
  • redirect_uri: String - URI de redirección de OAuth (ej. http://localhost:3080/api/mcp/${serverName}/oauth/callback)
  • scope: String - Alcances de OAuth (separados por espacios)
• Subclaves opcionales:
  • grant_types_supported: Matriz de Strings - Tipos de concesión admitidos (por defecto ["authorization_code", "refresh_token"])
  • token_endpoint_auth_methods_supported: Matriz de Strings - Métodos de autenticación del endpoint de token admitidos (por defecto ["client_secret_basic", "client_secret_post"])
  • token_exchange_method: String - Método de solicitud de intercambio de tokens. Utilice default_post para proveedores que esperan las credenciales de cliente OAuth en el cuerpo de la solicitud POST.
  • response_types_supported: Matriz de Strings - Tipos de respuesta admitidos (el valor predeterminado es ["code"])
  • code_challenge_methods_supported: Matriz de cadenas - Métodos de desafío de código PKCE admitidos (por defecto ["S256", "plain"])
  • skip_code_challenge_check: Booleano - Omite la verificación de si el proveedor de OAuth anuncia soporte para PKCE. Útil para proveedores como AWS Cognito que admiten S256 pero no lo anuncian en sus metadatos. (el valor predeterminado es false)
• Variables de entorno: Los campos de URL de OAuth definidos en YAML, incluyendo authorization_url, token_url, redirect_uri y revocation_endpoint, pueden utilizar referencias ${ENV_VAR}. LibreChat resuelve el valor del entorno antes de la validación de la URL. Las URLs de endpoint de OAuth gestionadas por el usuario y enviadas a través de la interfaz de usuario deben ser URLs literales y rechazar los marcadores de posición ${ENV_VAR}.
• Ejemplo:

  oauth-api-server:
    authorization_url: https://api.example.com/oauth/authorize
    token_url: https://api.example.com/oauth/token
    client_id: your_client_id
    client_secret: your_client_secret
    redirect_uri: http://localhost:3080/api/mcp/oauth-api-server/oauth/callback
    scope: 'read execute'
    grant_types_supported: ['authorization_code', 'refresh_token']
    token_endpoint_auth_methods_supported: ['client_secret_post']
    token_exchange_method: default_post
    response_types_supported: ['code']
    code_challenge_methods_supported: ['S256', 'plain']

oauth_headers

• Tipo: Objeto (Opcional)
• Descripción: Encabezados utilizados específicamente para solicitudes de flujo OAuth. Estos encabezados se utilizan durante la autenticación OAuth, como el registro dinámico de clientes y el intercambio de tokens, y no se envían durante la comunicación regular del servidor MCP.
• Casos de uso comunes:
  • Agregar autenticación a los endpoints de registro dinámico de clientes, como Authorization: Bearer ${DCR_API_KEY}
  • Incluyendo encabezados personalizados específicos del proveedor requeridos para flujos OAuth
  • Configuración de los encabezados necesarios para los endpoints de tokens OAuth
• Diferencias clave con headers:
  • headers: Se envían con las solicitudes regulares del servidor MCP una vez que se completa la autenticación
  • oauth_headers: Enviado solo durante los flujos de autenticación OAuth
• Ejemplo:

  oauth_headers:
    Authorization: "Bearer ${DCR_API_KEY}"
    X-Custom-Header: "custom_value"

startup

• Tipo: Booleano (Opcional)
• Descripción: Cuando se establece en false, este servidor MCP no se conectará al iniciar la aplicación. Esto es útil para servidores que requieren entrada o configuración del usuario antes de conectarse, o para casos en los que desea controlar cuándo se inicializa el servidor.
• Valor predeterminado: true
• Ejemplo:

  mcpServers:
    my-mcp-server:
      type: streamable-http
      url: 'https://api.example.com/mcp/'
      startup: false

Notas

• Inferencia de tipos:
  • Si se omite type:
    • Si se especifica url y comienza con http:// o https://, type toma sse como valor predeterminado.
    • Si se especifica url y comienza con ws:// o wss://, type toma websocket como valor predeterminado.
    • Si se especifica command, type toma stdio como valor predeterminado.
• Tipos de conexión:
  • stdio: Inicia un servidor MCP como un proceso hijo y se comunica a través de la entrada/salida estándar.
  • websocket: Se conecta a un servidor MCP externo a través de WebSocket.
  • sse: Se conecta a un servidor MCP externo a través de Server-Sent Events (SSE).
  • streamable-http: Se conecta a un servidor MCP externo a través de HTTP con soporte para respuestas en streaming.
• Direcciones internas/locales:
  • Importante: Los servidores MCP que utilizan direcciones IP internas (p. ej., 172.24.1.165, 192.168.1.100) o dominios locales (p. ej., mcp-server, host.docker.internal) deben ser permitidos explícitamente. Utilice mcpSettings.allowedAddresses para servicios específicos de host:puerto privados cuando desee que los destinos públicos sigan siendo accesibles, o mcpSettings.allowedDomains cuando desee una lista blanca estricta.
  • Consulta MCP Settings para obtener detalles sobre la configuración.

Ejemplos

Configuración con direcciones internas

Al usar servidores MCP internos/locales y no se necesite una lista blanca de dominios estricta, configure mcpSettings.allowedAddresses con el host y puerto exactos:

# MCP Settings - Required for internal/local addresses
mcpSettings:
  allowedAddresses:
    - '172.24.1.165:8000' # Internal IP and port
    - 'mcp-prod:8001' # Docker container and port
    - 'host.docker.internal:8080' # Docker host and port

# MCP Servers - Individual configurations
mcpServers:
  prod-mcp:
    type: streamable-http
    url: http://172.24.1.165:8000/mcp
    timeout: 120000

  test-mcp:
    type: streamable-http
    url: http://mcp-prod:8001/mcp
    timeout: 120000

Servidor MCP stdio

puppeteer:
  type: stdio
  command: npx
  args:
    - -y
    - '@modelcontextprotocol/server-puppeteer'
  timeout: 30000
  initTimeout: 10000
  env:
    NODE_ENV: 'production'
    USER_EMAIL: '{{LIBRECHAT_USER_EMAIL}}'
    USER_ROLE: '{{LIBRECHAT_USER_ROLE}}'
  stderr: inherit

Servidor MCP sse

everything:
  url: http://localhost:3001/sse
  headers:
    X-User-ID: '{{LIBRECHAT_USER_ID}}'
    X-API-Key: '${SOME_API_KEY}'

Servidor MCP websocket

myWebSocketServer:
  url: ws://localhost:8080

Servidor MCP streamable-http

streamable-http-server:
  type: streamable-http
  url: https://example.com/api/
  headers:
    X-User-ID: '{{LIBRECHAT_USER_ID}}'
    X-API-Key: '${SOME_API_KEY}'

Servidor MCP con campos de usuario dinámicos

user-aware-server:
  type: sse
  url: https://api.example.com/users/{{LIBRECHAT_USER_USERNAME}}/stream
  headers:
    X-User-ID: '{{LIBRECHAT_USER_ID}}'
    X-User-Email: '{{LIBRECHAT_USER_EMAIL}}'
    X-User-Role: '{{LIBRECHAT_USER_ROLE}}'
    X-Email-Verified: '{{LIBRECHAT_USER_EMAILVERIFIED}}'
    Authorization: 'Bearer ${API_TOKEN}'

Servidor MCP con credenciales por usuario a través de customUserVars

my-mcp-server:
  type: streamable-http
  url: 'https://api.example-service.com/api/' # Example URL
  headers:
    X-Auth-Token: '{{API_KEY}}' # Uses the API_KEY defined below
  customUserVars:
    API_KEY: # This key will be used as {{API_KEY}} in headers/url
      title: 'API Key' # This is the label shown above the input field
      description: "Get your API key <a href='https://example.com/api-keys' target='_blank'>here</a>." # This description appears below the input

NOTA: Consulta MCP Server Initialization para obtener más información sobre la inicialización de servidores basada en la interfaz de usuario.

Servidor MCP con icono personalizado

filesystem:
  command: npx
  args:
    - -y
    - '@modelcontextprotocol/server-filesystem'
    - /home/user/LibreChat/
  iconPath: /home/user/LibreChat/client/public/assets/logo.svg
  chatMenu: false # Exclude from chatarea dropdown

Servidor MCP con autenticación OAuth

oauth-api-server:
  type: streamable-http
  url: https://api.example.com/mcp/
  oauth:
    authorization_url: https://api.example.com/oauth/authorize
    token_url: https://api.example.com/oauth/token
    client_id: your_client_id
    client_secret: your_client_secret
    redirect_uri: http://localhost:3080/api/mcp/oauth-api-server/oauth/callback
    scope: 'read execute'
  oauth_headers:
    X-Custom-Header: 'custom_value'

Servidor MCP con Instrucciones del Servidor

# Server that uses its own provided instructions
web-search:
  type: streamable-http
  url: https://example.com/mcp/search
  serverInstructions: true

# Server with instructions explicitly disabled
filesystem:
  command: npx
  args:
    - -y
    - '@modelcontextprotocol/server-filesystem'
    - /home/user/documents/
  serverInstructions: false

# Server with custom instructions
puppeteer:
  type: stdio
  command: npx
  args:
    - -y
    - '@modelcontextprotocol/server-puppeteer'
  serverInstructions: |
    Browser automation security and best practices:
    1. Be cautious with local file access and internal IP addresses
    2. Take screenshots to verify successful page interactions
    3. Wait for page elements to load before interacting with them
    4. Use specific CSS selectors for reliable element targeting
    5. Check console logs for JavaScript errors when troubleshooting

Servidor MCP habilitado para OAuth (Legacy requiresOAuth)

composio-googlesheets:
  type: sse
  url: https://mcp.composio.dev/googlesheets/sse-endpoint
  requiresOAuth: true
  headers:
    X-User-ID: '{{LIBRECHAT_USER_ID}}'
    X-API-Key: '${COMPOSIO_API_KEY}'
  timeout: 45000
  initTimeout: 15000

Variables de entorno relacionadas (opcional):

# OAuth configuration for MCP servers
MCP_OAUTH_ON_AUTH_ERROR=true
MCP_OAUTH_DETECTION_TIMEOUT=10000
MCP_OAUTH_HANDLING_TIMEOUT=600000
MCP_OAUTH_FLOW_TTL=900000

# API key for the service
COMPOSIO_API_KEY=your_composio_api_key_here

Importar configuraciones de servidor MCP

Las configuraciones de mcpServers permiten a LibreChat interactuar dinámicamente con varios servidores MCP, los cuales pueden realizar tareas especializadas o proporcionar funcionalidades específicas dentro de la aplicación. Este enfoque modular facilita la extensión de las capacidades de la aplicación simplemente añadiendo o modificando las configuraciones del servidor.

Información adicional

• Comportamiento predeterminado:
  • La inicialización ocurre al iniciar, y la aplicación debe reiniciarse para que los cambios surtan efecto.
  • Si se especifican tanto url como command, el type debe definirse explícitamente para evitar ambigüedades.
• Soporte multiusuario:
  • El MCPManager ahora admite conexiones distintas a nivel de usuario y a nivel de aplicación, lo que permite una gestión de conexiones adecuada por usuario.
  • Las conexiones de usuario se rastrean y gestionan por separado, con el establecimiento y la limpieza adecuados.
  • Utilice marcadores de posición de campos de usuario dinámicos en encabezados, URLs y variables de entorno:
    • {{LIBRECHAT_USER_ID}} - Identificador único del usuario
    • {{LIBRECHAT_USER_EMAIL}} - Dirección de correo electrónico del usuario
    • {{LIBRECHAT_USER_USERNAME}} - Nombre de usuario del usuario
    • {{LIBRECHAT_USER_ROLE}} - Rol del usuario (p. ej., "user", "admin")
    • Y muchos más campos (consulta la sección de encabezados para ver la lista completa)
• Gestión de inactividad del usuario:
  • Las conexiones de usuario son monitoreadas por actividad y serán desconectadas después de 15 minutos de inactividad.
• Variables de entorno:
  • En env (para el tipo stdio): Útil para configurar entornos de ejecución específicos o configuraciones requeridas por el proceso del servidor MCP.
  • En headers (para los tipos sse y streamable-http): Utilice la sintaxis ${ENV_VAR} para hacer referencia a variables de entorno en los valores de los encabezados.
• Campos de usuario dinámicos:
  • Los marcadores de posición del campo de usuario se reemplazan en tiempo de ejecución con la información del usuario autenticado.
  • Solo los campos no confidenciales están disponibles (las contraseñas y otros datos confidenciales están excluidos)
  • Los campos faltantes se establecen de forma predeterminada como cadenas vacías
  • Los campos booleanos se convierten a representaciones de cadena ("true" o "false")
• Manejo de errores (stderr):
  • Configurar stderr le permite gestionar cómo se manejan los mensajes de error del proceso del servidor MCP. El valor predeterminado "inherit" significa que los errores se imprimirán en el stderr del proceso padre.
• Instrucciones del servidor:
  • Las instrucciones se inyectan automáticamente en el mensaje del sistema del agente cuando se utilizan herramientas de servidor MCP.
  • Las Custom instructions (valores de cadena) tienen prioridad sobre las instrucciones proporcionadas por el servidor
  • Múltiples servidores MCP pueden contribuir cada uno con sus propias instrucciones al contexto del agente
  • Las instrucciones solo se incluyen cuando las herramientas del servidor MCP correspondiente están realmente disponibles para el agente
• Autenticación OAuth:
  • El flujo OAuth2 es compatible para una autenticación segura con servidores MCP
  • Se solicitará a los usuarios que se autentiquen mediante OAuth antes de que se pueda utilizar el servidor MCP.

Referencias

• Documentación del Model Context Protocol (MCP)
• Especificación de transportes MCP
• Node.js child_process.spawn

Al configurar correctamente los mcpServers en tu librechat.yaml, puedes mejorar la funcionalidad de LibreChat e integrar herramientas y servicios personalizados sin problemas.