(Para o tipo `websocket`, `streamable-http` ou `sse`) A URL para conectar ao servidor MCP.
url: "http://localhost:3001/sse"
proxy
String
(Opcional, para tipos `sse` e `streamable-http`) URL de proxy de saĆda para este servidor MCP remoto. Suporta URLs `http://`, `https://`, `socks://` e `socks5://`.
proxy: "${MCP_PROXY_URL}"
headers
Object
(Opcional, para tipos `sse` e `streamable-http`) CabeƧalhos personalizados para enviar com a requisiĆ§Ć£o. Suporta substituiĆ§Ć£o dinĆ¢mica de campos do usuĆ”rio com placeholders `{{LIBRECHAT_USER_*}}` e variĆ”veis de ambiente com `${ENV_VAR}`.
(Opcional) 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.
serverInstructions: true
# or
serverInstructions: "Custom instructions"
timeout
Integer
(Opcional) Tempo limite em milissegundos para solicitaƧƵes de servidor MCP. Deve ser um nĆŗmero inteiro nĆ£o negativo.
timeout: 30000
initTimeout
Integer
(Opcional) Tempo limite em milissegundos para a inicializaĆ§Ć£o do servidor MCP. Deve ser um nĆŗmero inteiro nĆ£o negativo.
initTimeout: 10000
env
Object
(Opcional, apenas tipo `stdio`) VariƔveis de ambiente para usar ao iniciar o processo.
(Opcional) Define variĆ”veis personalizadas que os usuĆ”rios podem configurar para este servidor MCP, permitindo credenciais ou configuraƧƵes por usuĆ”rio (por exemplo, chaves de API). Essas variĆ”veis podem entĆ£o ser referenciadas nos campos `headers` ou `env`.
customUserVars:
API_KEY:
title: "API Key"
description: "Your personal API key."
oauth
Object
(Opcional) ConfiguraĆ§Ć£o OAuth2 para autenticaĆ§Ć£o com o servidor MCP. Quando configurado, os usuĆ”rios serĆ£o solicitados a autenticar via fluxo OAuth.
(Opcional) Mapa de nomes e valores de cabeƧalho usados apenas para solicitaƧƵes de fluxo OAuth, como registro dinĆ¢mico de cliente ou troca de token.
(Opcional, para tipos `sse` e `streamable-http`) ConfiguraĆ§Ć£o de troca de token On-Behalf-Of. Troca o token de acesso OpenID do usuĆ”rio atual por um token delegado downstream e o encaminha como um token Bearer.
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']
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://.
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:
Placeholder
User Field
Type
DescriĆ§Ć£o
{{LIBRECHAT_USER_NAME}}
name
String
Nome de exibiĆ§Ć£o do usuĆ”rio
{{LIBRECHAT_USER_USERNAME}}
username
String
Nome de usuƔrio
{{LIBRECHAT_USER_EMAIL}}
email
String
EndereƧo de e-mail do usuƔrio
{{LIBRECHAT_USER_PROVIDER}}
provider
String
Provedor de autenticaĆ§Ć£o (ex: "email", "google", "github")
{{LIBRECHAT_USER_ROLE}}
role
String
FunĆ§Ć£o do usuĆ”rio (ex: "user", "admin")
{{LIBRECHAT_USER_GOOGLEID}}
googleId
String
ID da conta Google
{{LIBRECHAT_USER_FACEBOOKID}}
facebookId
String
ID da conta Facebook
{{LIBRECHAT_USER_OPENIDID}}
openidId
String
ID da conta OpenID
{{LIBRECHAT_USER_SAMLID}}
samlId
String
ID da conta SAML
{{LIBRECHAT_USER_LDAPID}}
ldapId
String
ID da conta LDAP
{{LIBRECHAT_USER_GITHUBID}}
githubId
String
ID da conta GitHub
{{LIBRECHAT_USER_DISCORDID}}
discordId
String
ID da conta Discord
{{LIBRECHAT_USER_APPLEID}}
appleId
String
ID da conta Apple
{{LIBRECHAT_USER_EMAILVERIFIED}}
emailVerified
Boolean ā String
Status de verificaĆ§Ć£o de e-mail ("true" ou "false")
{{LIBRECHAT_USER_TWOFACTORENABLED}}
twoFactorEnabled
Boolean ā String
Status do 2FA ("true" ou "false")
{{LIBRECHAT_USER_TERMSACCEPTED}}
termsAccepted
Boolean ā String
Status de aceitaĆ§Ć£o dos termos ("true" ou "false")
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.
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:
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.
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 instructionsserverInstructions: true# Use custom instructionsserverInstructions: | When using this filesystem server: 1. Always use absolute paths for file operations 2. Check file permissions before attempting write operations# Explicitly disable instructionsserverInstructions: false
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
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).
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.
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>).
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}}.
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
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.
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.
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)
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
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.
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 addressesmcpSettings: 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 configurationsmcpServers: 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
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.
# Server that uses its own provided instructionsweb-search: type: streamable-http url: https://example.com/mcp/search serverInstructions: true# Server with instructions explicitly disabledfilesystem: command: npx args: - -y - '@modelcontextprotocol/server-filesystem' - /home/user/documents/ serverInstructions: false# Server with custom instructionspuppeteer: 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
# OAuth configuration for MCP serversMCP_OAUTH_ON_AUTH_ERROR=trueMCP_OAUTH_DETECTION_TIMEOUT=10000MCP_OAUTH_HANDLING_TIMEOUT=600000MCP_OAUTH_FLOW_TTL=900000# API key for the serviceCOMPOSIO_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.
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
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.
LibreChat
