Estrutura do Objeto de Servidores MCP

Exemplo

# 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>

Chave:

Subchaves

title

• Tipo: String (Opcional)
• Descrição: Nome de exibição personalizado para o servidor MCP na interface. Se não for especificado, o nome da chave do servidor será usado.
• Exemplo:

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

description

• Tipo: String (Opcional)
• Descrição: Descrição do servidor MCP, exibida na UI para ajudar os usuários a entender seu propósito e capacidades.
• Exemplo:

  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
• Descrição: Especifica o tipo de conexão com o servidor MCP. As opções válidas são "stdio", "websocket", "streamable-http" ou "sse".
• Valor Padrão: Determinado com base na presença e no formato de url ou command.

command

• Tipo: String
• Descrição: (Para o tipo stdio) O comando ou executável a ser executado para iniciar o servidor MCP.

args

• Tipo: Array de Strings
• Descrição: (Para o tipo stdio) Argumentos de linha de comando a serem passados para o command.

url

• Tipo: String
• Descrição: (Para o tipo websocket, streamable-http ou sse) A URL para conectar ao servidor MCP. Suporta placeholders dinâmicos de campos do usuário ({{LIBRECHAT_USER_*}}) e substituição de variáveis de ambiente (${ENV_VAR}).
• Notas:
  • Para o tipo sse, a URL deve começar com http:// ou https://.
  • Para o tipo streamable-http, a URL deve começar com http:// ou https://.
  • Para o tipo websocket, a URL deve começar com ws:// ou wss://.

proxy

• Tipo: String (Opcional, para tipos sse e streamable-http)
• Descrição: URL de proxy de saída para este servidor MCP remoto. O valor pode referenciar variáveis de ambiente com ${ENV_VAR}.
• Protocolos suportados: http://, https://, socks:// e socks5://
• Nota de segurança: proxy é controlado pelo administrador. Ele resolve variáveis de ambiente, mas não resolve espaços reservados controlados pelo usuário, como {{LIBRECHAT_USER_ID}} ou customUserVars.
• Exemplo:

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

headers

• Tipo: Objeto (Opcional, para os tipos sse e streamable-http)
• Descrição: Cabeçalhos personalizados para enviar com a solicitação. Suporta vários tipos de placeholders para substituição dinâmica de valores.
• Suporte a Placeholder:
  • {{LIBRECHAT_USER_ID}}: Será substituído pelo ID do usuário atual, permitindo suporte a múltiplos usuários.
  • {{LIBRECHAT_USER_*}}: Placeholders de campo de usuário dinâmicos. Substitua * pela versão em MAIÚSCULAS de qualquer campo permitido.
  • {{LIBRECHAT_OPENID_*}}: Placeholders de token/sessão OpenID para servidores definidos em YAML.
  • {{LIBRECHAT_GRAPH_*}}: Placeholders de token do Microsoft Graph para servidores definidos em YAML.
  • {{LIBRECHAT_BODY_*}}: Placeholders de corpo de requisição para servidores definidos em YAML, como o conversationId, parentMessageId ou messageId atuais.
  • {{CUSTOM_VARIABLE_NAME}}: Substituído pelo valor fornecido pelo usuário para uma variável definida em customUserVars (por exemplo, {{MY_API_KEY}}).
  • ${ENV_VAR}: Será substituído pelo valor da variável de ambiente {{ENV_VAR}}.

Placeholders de Campo de Usuário Disponíveis:

Nota: Campos ausentes serão substituídos por strings vazias.

Os placeholders {{LIBRECHAT_BODY_*}} têm escopo de requisição. O LibreChat cria a conexão MCP para a execução ativa, reutiliza-a em chamadas de ferramentas durante essa execução e a encerra quando a requisição termina. Servidores com escopo de requisição são excluídos do cache persistente de ferramentas para que cabeçalhos e URLs específicos da requisição não sejam reutilizados fora da execução ativa. Os placeholders {{LIBRECHAT_USER_*}}, {{LIBRECHAT_OPENID_*}} e {{LIBRECHAT_GRAPH_*}} ainda tornam o servidor com escopo de usuário, mas os transportes HTTP atualizam os cabeçalhos resolvidos antes de cada chamada de ferramenta sem forçar uma reconexão por conta própria.

• Exemplo:

  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 os tipos sse e streamable-http)

• Descrição: Configuração de autenticação por chave de API para o servidor MCP. Fornece uma maneira estruturada de configurar a autenticação baseada em chave de API.

• Sub-chaves:

  • source: String - De onde a chave de API vem. Opções:
    • "admin": A chave de API é configurada pelo administrador (em variáveis de ambiente ou no arquivo de configuração)
    • "user": A chave de API é fornecida pelo usuário através da UI
  • authorization_type: String - Como a chave de API é enviada nas requisições. Opções:
    • "bearer": Enviado como Authorization: Bearer <key>
    • "basic": Enviado como Authorization: Basic <key>
    • "custom": Enviado em um cabeçalho personalizado (requer custom_header)
  • custom_header: String - (Obrigatório quando authorization_type for "custom") O nome do cabeçalho a ser usado para a chave de API

• Exemplo:

  # 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: String (Opcional)
• Descrição: Define o ícone de exibição da ferramenta mostrado na caixa de diálogo de seleção de ferramentas.

chatMenu

• Tipo: Booleano (Opcional)
• Descrição: Quando definido como false, exclui o servidor MCP do menu suspenso da área de chat (MCPSelect) para acesso rápido e fácil.
• Valor Padrão: true (O servidor MCP será incluído no menu suspenso da área de chat)

serverInstructions

• Tipo: Booleano ou String (Opcional)

• Descrição: Controla como as instruções do servidor MCP são injetadas no contexto do agente. As instruções do servidor fornecem orientações de uso de alto nível para todo o servidor MCP, complementando as descrições individuais das ferramentas.

• Opções:

  • undefined (padrão): Nenhuma instrução é incluída
  • true: Use as instruções fornecidas pelo servidor (se disponíveis) - ideal para servidores bem documentados com orientações abrangentes
  • false: Desativa explicitamente as instruções - útil para economizar tokens de contexto ou quando as ferramentas são autoexplicativas
  • string: Use instruções personalizadas (substituem as fornecidas pelo servidor) - ideal para fluxos de trabalho específicos da aplicação ou quando as instruções do servidor são insuficientes

• Valor Padrão: undefined (nenhuma instrução incluída)

• Notas:

  • As instruções são injetadas automaticamente quando serverInstructions está configurado e as ferramentas do servidor estão disponíveis para o agente
  • Vários servidores podem contribuir com instruções para o contexto do agente

• Exemplo:

  # 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, apenas tipo stdio)
• Descrição: Variáveis de ambiente a serem usadas ao iniciar o processo.
• Suporte a Placeholder:
  • {{LIBRECHAT_USER_ID}}: Substituído pelo ID do usuário atual.
  • {{LIBRECHAT_USER_*}}: Espaços reservados dinâmicos para campos de usuário (por exemplo, {{LIBRECHAT_USER_EMAIL}}).
  • {{CUSTOM_VARIABLE_NAME}}: Substituído pelo valor fornecido pelo usuário para uma variável definida em customUserVars (por exemplo, {{MY_API_KEY}}).
  • ${ENV_VAR}: Substituído pelo valor da variável de ambiente do lado do servidor {{ENV_VAR}}.

timeout

• Tipo: Inteiro (Opcional)
• Descrição: Tempo limite em milissegundos para solicitações de servidor MCP. Deve ser um número inteiro não negativo.
• Valor Padrão: 30000 (30 segundos)

initTimeout

• Tipo: Inteiro (Opcional)
• Descrição: Tempo limite em milissegundos para a inicialização do servidor MCP. Deve ser um número inteiro não negativo.
• Valor Padrão: 10000 (10 segundos)

requiresOAuth

• Tipo: Booleano (Opcional, apenas para transportes remotos: sse, streamable-http, websocket)
• Descrição: Se este servidor requer autenticação OAuth. Se não for especificado, será detectado automaticamente durante a inicialização do servidor. Embora seja opcional, é melhor definir este valor explicitamente se você souber se o servidor requer OAuth ou não.
• Valor Padrão: Detectado automaticamente se não especificado
• Notas:
  • Aplicável a transportes remotos (baseados em URL): sse, streamable-http e websocket. Não tem efeito em servidores stdio, que não possuem URL para autenticação.
  • A detecção automática ocorre durante a inicialização do servidor, o que pode aumentar o tempo de inicialização.
  • A configuração explícita melhora o desempenho de inicialização ao ignorar a detecção
  • Defina requiresOAuth: false para servidores protegidos apenas por um cabeçalho Authorization estático (por exemplo, uma chave de API Bearer). A detecção automática sonda o servidor sem os seus cabeçalhos configurados, portanto, um servidor que responde com 401 com um desafio WWW-Authenticate: Bearer pode ser classificado incorretamente como protegido por OAuth; este sinalizador ignora essa sonda e permite que o seu cabeçalho estático autentique a conexão normalmente.
  • Funciona com variáveis de ambiente MCP OAuth (MCP_OAUTH_ON_AUTH_ERROR, MCP_OAUTH_DETECTION_TIMEOUT, MCP_OAUTH_HANDLING_TIMEOUT, MCP_OAUTH_FLOW_TTL) para um gerenciamento de conexão aprimorado

stderr

• Tipo: String ou Integer (Opcional, apenas para o tipo stdio)
• Descrição: Como lidar com o stderr do processo filho. Isso corresponde à semântica do child_process.spawn do Node. Valores de string válidos: "pipe", "ignore", "inherit". Alternativamente, um número inteiro não negativo pode ser usado como um descritor de arquivo.
• Valor Padrão: "inherit" (mensagens para stderr serão impressas no stderr do processo pai).

customUserVars

• Tipo: Objeto (Opcional)
• Descrição: Define variáveis personalizadas que os usuários podem configurar para este servidor MCP. Isso permite que administradores especifiquem variáveis (por exemplo, chaves de API, URLs) que cada usuário deve configurar individualmente. Esses valores fornecidos pelo usuário podem então ser usados na configuração de headers ou env. Servidores com customUserVars são automaticamente excluídos de conexões em nível de aplicativo, garantindo que as credenciais por usuário sejam sempre resolvidas em tempo de execução.
• Estrutura:
  • O objeto customUserVars contém chaves, onde cada chave representa um nome de variável (por exemplo, MY_API_KEY). Este nome será usado em placeholders como {{MY_API_KEY}}.
  • Cada nome de variável é um objeto com as seguintes subchaves:
    • title: String (Obrigatório) - Um título amigável para a variável, exibido na interface de configuração.
    • 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: Boolean (Opcional) - Controla se o valor é tratado como um segredo e mascarado na interface. O padrão é o comportamento mascarado/secreto quando omitido; defina como false para campos que não são secretos, como IDs de projeto ou URLs base.
• Uso em headers e env:
  • Uma vez definidas em customUserVars, essas variáveis podem ser referenciadas nas seções headers (para os tipos sse e streamable-http) ou env (para o tipo stdio) usando a sintaxe {{VARIABLE_NAME}}.
  • Os usuários fornecem esses valores através da UI. Essas configurações podem ser acessadas de duas maneiras:
    • From Assistant Chat Input: Ao selecionar ferramentas MCP para um assistente, um ícone de configurações aparecerá ao lado dos servidores MCP configuráveis no menu suspenso de seleção de ferramentas. Clicar neste ícone abre uma caixa de diálogo para gerenciar as credenciais daquele servidor.
    • No Painel de Configurações: Uma seção dedicada de "MCP Settings" no painel direito lista todos os servidores MCP com variáveis personalizadas definíveis. Os usuários podem clicar em um servidor para abrir a caixa de diálogo de configuração para definir ou atualizar suas credenciais para aquele servidor MCP específico.
  • Esses valores fornecidos pelo usuário são armazenados de forma segura, associados ao usuário individual e ao servidor MCP específico, e substituídos em tempo de execução.
• Exemplo:

  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 em 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, apenas para os tipos sse e streamable-http)
• Descrição: Configura a troca de token OAuth 2.0 On-Behalf-Of para um servidor MCP. O LibreChat troca o token de acesso OpenID do usuário logado por um token delegado de downstream com os escopos configurados, e então encaminha esse token para o servidor MCP como um cabeçalho Authorization: Bearer ....
• Subchaves obrigatórias:
  • scopes: String - Escopos não vazios solicitados para a troca de token downstream.
• Validação:
  • obo é válido apenas para servidores MCP sse e streamable-http.
  • obo é rejeitado para servidores stdio e websocket.
  • Os usuários precisam da permissão de função MCP_SERVERS.CONFIGURE_OBO para configurar este campo. Defina-o com interface.mcpServers.configureObo ou gerencie-o a partir do painel de administração.
• Pré-requisitos:
  • A autenticação OpenID deve ser configurada com tokens de acesso reutilizáveis.
  • Seu provedor de identidade e a aplicação downstream devem permitir o escopo delegado solicitado.
• Exemplo:

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

Veja OpenID Connect Token Reuse e SharePoint Integration para configurações relacionadas de reutilização de token e token delegado.

oauth

• Tipo: Objeto (Opcional)
• Descrição: Configuração OAuth2 para autenticação com o servidor MCP. Quando configurado, os usuários serão solicitados a autenticar via fluxo OAuth antes que o servidor MCP possa ser usado. Se nenhum client id e client secret forem fornecidos, o Dynamic Client Registration (DCR) será utilizado.
• Subchaves obrigatórias:
  • authorization_url: String - A URL do endpoint de autorização OAuth
  • token_url: String - A URL do endpoint de token OAuth
  • client_id: String - Identificador de cliente OAuth
  • client_secret: String - Segredo do cliente OAuth
  • redirect_uri: String - URI de redirecionamento OAuth (ex: http://localhost:3080/api/mcp/${serverName}/oauth/callback)
  • scope: String - Escopos OAuth (separados por espaço)
• Subchaves Opcionais:
  • grant_types_supported: Array de Strings - Tipos de concessão suportados (o padrão é ["authorization_code", "refresh_token"])
  • token_endpoint_auth_methods_supported: Array de Strings - Métodos de autenticação de endpoint de token suportados (o padrão é ["client_secret_basic", "client_secret_post"])
  • token_exchange_method: String - Método de solicitação de troca de token. Use default_post para provedores que esperam as credenciais do cliente OAuth no corpo da requisição POST.
  • response_types_supported: Array de Strings - Tipos de resposta suportados (o padrão é ["code"])
  • code_challenge_methods_supported: Array de Strings - Métodos de desafio de código PKCE suportados (o padrão é ["S256", "plain"])
  • skip_code_challenge_check: Boolean - Pula a verificação se o provedor OAuth anuncia suporte a PKCE. Útil para provedores como AWS Cognito que suportam S256, mas não o anunciam em seus metadados. (o padrão é false)
• Variáveis de ambiente: Os campos de URL de OAuth definidos no YAML, incluindo authorization_url, token_url, redirect_uri e revocation_endpoint, podem usar referências ${ENV_VAR}. O LibreChat resolve o valor do ambiente antes da validação da URL. URLs de endpoint OAuth gerenciadas pelo usuário enviadas através da interface devem ser URLs literais e rejeitar espaços reservados ${ENV_VAR}.
• Exemplo:

  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)
• Descrição: Cabeçalhos usados especificamente para solicitações de fluxo OAuth. Esses cabeçalhos são usados durante a autenticação OAuth, como registro dinâmico de cliente e troca de tokens, e não são enviados durante a comunicação regular do servidor MCP.
• Casos de Uso Comuns:
  • Adicionando autenticação a endpoints de registro dinâmico de cliente, como Authorization: Bearer ${DCR_API_KEY}
  • Incluindo cabeçalhos específicos de provedores personalizados necessários para fluxos OAuth
  • Configurando cabeçalhos necessários pelos endpoints de token OAuth
• Principais diferenças de headers:
  • headers: Enviado com solicitações regulares do servidor MCP após a conclusão da autenticação
  • oauth_headers: Enviado apenas durante fluxos de autenticação OAuth
• Exemplo:

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

startup

• Tipo: Booleano (Opcional)
• Descrição: Quando definido como false, este servidor MCP não será conectado na inicialização da aplicação. Isso é útil para servidores que exigem entrada ou configuração do usuário antes de conectar, ou para casos em que você deseja controlar quando o servidor é inicializado.
• Valor Padrão: true
• Exemplo:

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

Notas

• Inferência de Tipo:
  • Se type for omitido:
    • Se url for especificado e começar com http:// ou https://, type assume sse como padrão.
    • Se url for especificado e começar com ws:// ou wss://, type assume websocket como padrão.
    • Se command for especificado, type assume stdio como padrão.
• Tipos de Conexão:
  • stdio: Inicia um servidor MCP como um processo filho e comunica-se via entrada/saída padrão.
  • websocket: Conecta-se a um servidor MCP externo via WebSocket.
  • sse: Conecta-se a um servidor MCP externo via Server-Sent Events (SSE).
  • streamable-http: Conecta-se a um servidor MCP externo via HTTP com suporte para respostas em streaming.
• Endereços Internos/Locais:
  • Importante: Servidores MCP que utilizam endereços IP internos (por exemplo, 172.24.1.165, 192.168.1.100) ou domínios locais (por exemplo, mcp-server, host.docker.internal) devem ser explicitamente permitidos. Use mcpSettings.allowedAddresses para serviços específicos de host:porta privados quando desejar que destinos públicos permaneçam acessíveis, ou mcpSettings.allowedDomains quando desejar uma lista de permissões (whitelist) rigorosa.
  • Veja MCP Settings para detalhes de configuração.

Exemplos

Configuração com Endereços Internos

Ao usar servidores MCP internos/locais e quando não for necessária uma lista de permissões de domínio estrita, configure mcpSettings.allowedAddresses com o host e a porta exatos:

# 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 com Campos de Usuário 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 com Credenciais por Usuário via 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 Veja MCP Server Initialization para mais informações sobre a inicialização de servidor baseada na interface do usuário.

Servidor MCP com Ícone 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 com Autenticação 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 com Instruções do 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 com OAuth habilitado (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

Variáveis de Ambiente 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

Importando Configurações de Servidor MCP

As configurações mcpServers permitem que o LibreChat interaja dinamicamente com vários servidores MCP, os quais podem realizar tarefas especializadas ou fornecer funcionalidades específicas dentro da aplicação. Essa abordagem modular facilita a extensão das capacidades da aplicação simplesmente adicionando ou modificando configurações de servidor.

Informações Adicionais

• Comportamento Padrão:
  • A inicialização ocorre na inicialização, e o aplicativo deve ser reiniciado para que as alterações entrem em vigor.
  • Se tanto url quanto command forem especificados, o type deve ser definido explicitamente para evitar ambiguidade.
• Suporte a Múltiplos Usuários:
  • O MCPManager agora suporta conexões distintas em nível de usuário e em nível de aplicativo, permitindo o gerenciamento adequado de conexões por usuário.
  • As conexões dos usuários são rastreadas e gerenciadas separadamente, com o devido estabelecimento e limpeza.
  • Use espaços reservados de campo de usuário dinâmicos em cabeçalhos, URLs e variáveis de ambiente:
    • {{LIBRECHAT_USER_ID}} - Identificador único do usuário
    • {{LIBRECHAT_USER_EMAIL}} - Endereço de e-mail do usuário
    • {{LIBRECHAT_USER_USERNAME}} - Nome de usuário do usuário
    • {{LIBRECHAT_USER_ROLE}} - Função do usuário (por exemplo, "user", "admin")
    • E muitos outros campos (veja a seção headers para a lista completa)
• Gerenciamento de Inatividade do Usuário:
  • As conexões dos usuários são monitoradas quanto à atividade e serão desconectadas após 15 minutos de inatividade.
• Variáveis de Ambiente:
  • Em env (para o tipo stdio): Útil para configurar ambientes de execução específicos ou configurações necessárias para o processo do servidor MCP.
  • Em headers (para os tipos sse e streamable-http): Use a sintaxe ${ENV_VAR} para referenciar variáveis de ambiente nos valores dos cabeçalhos.
• Campos de Usuário Dinâmicos:
  • Os placeholders de campo do usuário são substituídos em tempo de execução pelas informações do usuário autenticado
  • Apenas campos não sensíveis estão disponíveis (senhas e outros dados sensíveis são excluídos)
  • Campos ausentes são definidos como strings vazias por padrão
  • Campos booleanos são convertidos para representações em string ("true" ou "false")
• Tratamento de erros (stderr):
  • Configurar o stderr permite que você gerencie como as mensagens de erro do processo do servidor MCP são tratadas. O padrão "inherit" significa que os erros serão impressos no stderr do processo pai.
• Instruções do Servidor:
  • As instruções são injetadas automaticamente na mensagem de sistema do agente quando ferramentas de servidor MCP são usadas.
  • As Custom instructions (valores de string) têm precedência sobre as instruções fornecidas pelo servidor
  • Vários servidores MCP podem contribuir, cada um, com suas próprias instruções para o contexto do agente
  • As instruções só são incluídas quando as ferramentas do servidor MCP correspondente estão realmente disponíveis para o agente
• Autenticação OAuth:
  • O fluxo OAuth2 é suportado para autenticação segura com servidores MCP
  • Os usuários serão solicitados a autenticar via OAuth antes que o servidor MCP possa ser usado

Referências

• Documentação do Model Context Protocol (MCP)
• Especificação de Transportes MCP
• Node.js child_process.spawn

Ao configurar corretamente os mcpServers no seu librechat.yaml, você pode aprimorar a funcionalidade do LibreChat e integrar ferramentas e serviços personalizados de forma integrada.