Struttura dell'oggetto MCP Servers

Esempio

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

Chiave:

Sottochiavi

title

• Tipo: Stringa (Opzionale)
• Descrizione: Nome visualizzato personalizzato per il server MCP nell'interfaccia utente. Se non specificato, viene utilizzato il nome della chiave del server.
• Esempio:

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

description

• Tipo: Stringa (Opzionale)
• Descrizione: Descrizione del server MCP, visualizzata nell'interfaccia utente per aiutare gli utenti a comprenderne lo scopo e le funzionalità.
• Esempio:

  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
• Descrizione: Specifica il tipo di connessione al server MCP. Le opzioni valide sono "stdio", "websocket", "streamable-http" o "sse".
• Valore predefinito: Determinato in base alla presenza e al formato di url o command.

command

• Tipo: String
• Descrizione: (Per il tipo stdio) Il comando o l'eseguibile da eseguire per avviare il server MCP.

args

• Tipo: Array di stringhe
• Descrizione: (Per il tipo stdio) Argomenti della riga di comando da passare al command.

url

• Tipo: String
• Descrizione: (Per il tipo websocket, streamable-http o sse) L'URL a cui connettersi al server MCP. Supporta segnaposto dinamici per i campi utente ({{LIBRECHAT_USER_*}}) e la sostituzione delle variabili d'ambiente (${ENV_VAR}).
• Note:
  • Per il tipo sse, l'URL deve iniziare con http:// o https://.
  • Per il tipo streamable-http, l'URL deve iniziare con http:// o https://.
  • Per il tipo websocket, l'URL deve iniziare con ws:// o wss://.

proxy

• Tipo: Stringa (Opzionale, per i tipi sse e streamable-http)
• Descrizione: URL del proxy in uscita per questo server MCP remoto. Il valore può fare riferimento a variabili d'ambiente con ${ENV_VAR}.
• Protocolli supportati: http://, https://, socks:// e socks5://
• Nota sulla sicurezza: proxy è controllato dall'amministratore. Risolve le variabili d'ambiente, ma non risolve i segnaposto controllati dall'utente come {{LIBRECHAT_USER_ID}} o customUserVars.
• Esempio:

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

headers

• Tipo: Oggetto (Opzionale, per i tipi sse e streamable-http)
• Descrizione: Header personalizzati da inviare con la richiesta. Supporta vari tipi di segnaposto per la sostituzione dinamica dei valori.
• Supporto segnaposto:
  • {{LIBRECHAT_USER_ID}}: Verrà sostituito con l'ID dell'utente corrente, abilitando il supporto multi-utente.
  • {{LIBRECHAT_USER_*}}: Segnaposto dinamici per i campi utente. Sostituisci * con la versione in MAIUSCOLO di qualsiasi campo consentito.
  • {{LIBRECHAT_OPENID_*}}: segnaposto per token/sessione OpenID per server definiti in YAML.
  • {{LIBRECHAT_GRAPH_*}}: segnaposto dei token di Microsoft Graph per i server definiti in YAML.
  • {{LIBRECHAT_BODY_*}}: Segnaposto del corpo della richiesta per server definiti in YAML, come i correnti conversationId, parentMessageId o messageId.
  • {{CUSTOM_VARIABLE_NAME}}: Sostituito con il valore fornito dall'utente per una variabile definita in customUserVars (ad esempio, {{MY_API_KEY}}).
  • ${ENV_VAR}: Verrà sostituito con il valore della variabile d'ambiente {{ENV_VAR}}.

Segnaposto dei campi utente disponibili:

Nota: I campi mancanti verranno sostituiti con stringhe vuote.

I segnaposto {{LIBRECHAT_BODY_*}} hanno un ambito limitato alla richiesta (request-scoped). LibreChat crea la connessione MCP per l'esecuzione attiva, la riutilizza tra le chiamate agli strumenti durante tale esecuzione e la chiude al termine della richiesta. I server con ambito limitato alla richiesta sono esclusi dalla cache persistente degli strumenti, in modo che le intestazioni e gli URL specifici della richiesta non vengano riutilizzati al di fuori dell'esecuzione attiva. I segnaposto {{LIBRECHAT_USER_*}}, {{LIBRECHAT_OPENID_*}} e {{LIBRECHAT_GRAPH_*}} rendono comunque il server con ambito limitato all'utente (user-scoped), ma i trasporti HTTP aggiornano le intestazioni risolte prima di ogni chiamata allo strumento senza forzare autonomamente una riconnessione.

• Esempio:

  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: Oggetto (Opzionale, per i tipi sse e streamable-http)

• Descrizione: Configurazione dell'autenticazione tramite chiave API per il server MCP. Fornisce un modo strutturato per configurare l'autenticazione basata su chiave API.

• Sotto-chiavi:

  • source: String - Da dove proviene la chiave API. Opzioni:
    • "admin": La chiave API è configurata dall'amministratore (nelle variabili d'ambiente o nella configurazione)
    • "user": la chiave API viene fornita dall'utente tramite l'interfaccia utente
  • authorization_type: String - Il modo in cui la chiave API viene inviata nelle richieste. Opzioni:
    • "bearer": Inviato come Authorization: Bearer <key>
    • "basic": Inviato come Authorization: Basic <key>
    • "custom": Inviato in un header personalizzato (richiede custom_header)
  • custom_header: String - (Obbligatorio quando authorization_type è "custom") Il nome dell'intestazione da utilizzare per la chiave API

• Esempio:

  # 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: Stringa (Opzionale)
• Descrizione: Definisce l'icona di visualizzazione dello strumento mostrata nella finestra di dialogo di selezione dello strumento.

chatMenu

• Tipo: Booleano (Opzionale)
• Descrizione: Quando impostato su false, esclude il server MCP dal menu a tendina dell'area chat (MCPSelect) per un accesso rapido e semplice.
• Valore predefinito: true (Il server MCP verrà incluso nel menu a discesa dell'area di chat)

serverInstructions

• Tipo: Booleano o Stringa (Opzionale)

• Descrizione: Controlla come le istruzioni del server MCP vengono iniettate nel contesto dell'agente. Le istruzioni del server forniscono una guida all'utilizzo di alto livello per l'intero server MCP, integrando le descrizioni dei singoli strumenti.

• Opzioni:

  • undefined (predefinito): Nessuna istruzione è inclusa
  • true: Utilizza le istruzioni fornite dal server (se disponibili) - ideale per server ben documentati con una guida completa
  • false: Disabilita esplicitamente le istruzioni - utile per risparmiare token di contesto o quando gli strumenti sono autoesplicativi
  • string: Utilizza istruzioni personalizzate (sovrascrivono quelle fornite dal server) - ideale per flussi di lavoro specifici dell'applicazione o quando le istruzioni del server non sono sufficienti

• Valore predefinito: undefined (nessuna istruzione inclusa)

• Note:

  • Le istruzioni vengono iniettate automaticamente quando serverInstructions è configurato e gli strumenti del server sono disponibili per l'agente.
  • Più server possono contribuire ciascuno con istruzioni al contesto dell'agente

• Esempio:

  # 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: Oggetto (Opzionale, solo tipo stdio)
• Descrizione: Variabili d'ambiente da utilizzare durante la generazione del processo.
• Supporto segnaposto:
  • {{LIBRECHAT_USER_ID}}: Sostituito con l'ID dell'utente corrente.
  • {{LIBRECHAT_USER_*}}: Segnaposto dinamici per i campi utente (es. {{LIBRECHAT_USER_EMAIL}}).
  • {{CUSTOM_VARIABLE_NAME}}: Sostituito con il valore fornito dall'utente per una variabile definita in customUserVars (ad esempio, {{MY_API_KEY}}).
  • ${ENV_VAR}: Sostituito con il valore della variabile d'ambiente lato server {{ENV_VAR}}.

timeout

• Tipo: Intero (Opzionale)
• Descrizione: Timeout in millisecondi per le richieste al server MCP. Deve essere un numero intero non negativo.
• Valore predefinito: 30000 (30 secondi)

initTimeout

• Tipo: Intero (Opzionale)
• Descrizione: Timeout in millisecondi per l'inizializzazione del server MCP. Deve essere un numero intero non negativo.
• Valore predefinito: 10000 (10 secondi)

requiresOAuth

• Tipo: Booleano (Opzionale, solo per trasporti remoti: sse, streamable-http, websocket)
• Descrizione: Indica se questo server richiede l'autenticazione OAuth. Se non specificato, verrà rilevato automaticamente all'avvio del server. Sebbene sia facoltativo, è preferibile impostare questo valore esplicitamente se si sa se il server richiede o meno OAuth.
• Valore predefinito: Rilevato automaticamente se non specificato
• Note:
  • Applicabile ai trasporti remoti (basati su URL): sse, streamable-http e websocket. Non ha alcun effetto sui server stdio, che non hanno un URL su cui autenticarsi.
  • Il rilevamento automatico avviene durante l'avvio del server, il che potrebbe aumentare il tempo di inizializzazione.
  • La configurazione esplicita migliora le prestazioni all'avvio saltando il rilevamento
  • Imposta requiresOAuth: false per i server protetti solo da un'intestazione Authorization statica (ad esempio, una chiave API Bearer). Il rilevamento automatico esegue il probe del server senza le intestazioni configurate, quindi un server che risponde con un errore 401 e una richiesta WWW-Authenticate: Bearer può essere erroneamente classificato come protetto da OAuth; questo flag ignora tale probe e consente alla tua intestazione statica di autenticare la connessione normalmente.
  • Funziona con le variabili d'ambiente MCP OAuth (MCP_OAUTH_ON_AUTH_ERROR, MCP_OAUTH_DETECTION_TIMEOUT, MCP_OAUTH_HANDLING_TIMEOUT, MCP_OAUTH_FLOW_TTL) per una gestione avanzata delle connessioni

stderr

• Tipo: Stringa o Intero (Opzionale, solo tipo stdio)
• Descrizione: Come gestire stderr del processo figlio. Questo corrisponde alla semantica di child_process.spawn di Node. Valori stringa validi: "pipe", "ignore", "inherit". In alternativa, è possibile utilizzare un numero intero non negativo come descrittore di file.
• Valore predefinito: "inherit" (i messaggi verso stderr verranno stampati sullo stderr del processo genitore).

customUserVars

• Tipo: Oggetto (Opzionale)
• Descrizione: Definisce variabili personalizzate che gli utenti possono impostare per questo server MCP. Ciò consente agli amministratori di specificare variabili (ad esempio, chiavi API, URL) che ogni utente deve configurare individualmente. Questi valori forniti dall'utente possono quindi essere utilizzati nella configurazione di headers o env. I server con customUserVars vengono automaticamente esclusi dalle connessioni a livello di app, garantendo che le credenziali per utente vengano sempre risolte in fase di esecuzione.
• Struttura:
  • L'oggetto customUserVars contiene chiavi, dove ogni chiave rappresenta un nome di variabile (ad esempio, MY_API_KEY). Questo nome verrà utilizzato nei segnaposto come {{MY_API_KEY}}.
  • Ogni nome di variabile è un oggetto con le seguenti sottochiavi:
    • title: String (Obbligatorio) - Un titolo intuitivo per la variabile, visualizzato nell'interfaccia di configurazione.
    • 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 (Opzionale) - Controlla se il valore viene trattato come un segreto e mascherato nell'interfaccia utente. Per impostazione predefinita, se omesso, il comportamento è mascherato/segreto; impostare su false per campi non segreti come ID progetto o URL di base.
• Utilizzo in headers e env:
  • Una volta definite sotto customUserVars, queste variabili possono essere referenziate nelle sezioni headers (per i tipi sse e streamable-http) o env (per il tipo stdio) utilizzando la sintassi {{VARIABLE_NAME}}.
  • Gli utenti forniscono questi valori tramite l'interfaccia utente. È possibile accedere a queste impostazioni in due modi:
    • Dall'input della chat dell'assistente: Quando si selezionano gli strumenti MCP per un assistente, apparirà un'icona delle impostazioni accanto ai server MCP configurabili nel menu a discesa della selezione degli strumenti. Cliccando su questa icona si apre una finestra di dialogo per gestire le credenziali di quel server.
    • Dal pannello Impostazioni: Una sezione dedicata "MCP Settings" nel pannello di destra elenca tutti i server MCP con variabili personalizzate definibili. Gli utenti possono fare clic su un server per aprire la finestra di dialogo di configurazione per impostare o aggiornare le proprie credenziali per quello specifico server MCP.
  • Questi valori forniti dall'utente vengono archiviati in modo sicuro, associati al singolo utente e allo specifico server MCP, e sostituiti in fase di esecuzione.
• Esempio:

  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

  Utilizzo in 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: Oggetto (Opzionale, solo per i tipi sse e streamable-http)
• Descrizione: Configura lo scambio di token OAuth 2.0 On-Behalf-Of per un server MCP. LibreChat scambia il token di accesso OpenID dell'utente connesso con un token delegato downstream con gli scope configurati, quindi inoltra tale token al server MCP come header Authorization: Bearer ....
• Sottochiavi richieste:
  • scopes: String - Scopes non vuoti richiesti per lo scambio di token a valle.
• Validazione:
  • obo è valido solo per i server MCP sse e streamable-http.
  • obo viene rifiutato per i server stdio e websocket.
  • Gli utenti necessitano dell'autorizzazione del ruolo MCP_SERVERS.CONFIGURE_OBO per configurare questo campo. Impostalo inizialmente con interface.mcpServers.configureObo o gestiscilo dal pannello di amministrazione.
• Prerequisiti:
  • L'autenticazione OpenID deve essere configurata con token di accesso riutilizzabili.
  • Il tuo identity provider e l'applicazione downstream devono consentire l'ambito delegato richiesto.
• Esempio:

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

Vedi OpenID Connect Token Reuse e SharePoint Integration per la configurazione correlata del riutilizzo dei token e dei token delegati.

oauth

• Tipo: Oggetto (Opzionale)
• Descrizione: Configurazione OAuth2 per l'autenticazione con il server MCP. Una volta configurato, agli utenti verrà richiesto di autenticarsi tramite il flusso OAuth prima che il server MCP possa essere utilizzato. Se non vengono forniti client id e client secret, verrà utilizzata la Dynamic Client Registration (DCR).
• Sottochiavi richieste:
  • authorization_url: String - L'URL dell'endpoint di autorizzazione OAuth
  • token_url: String - L'URL dell'endpoint del token OAuth
  • client_id: String - Identificativo client OAuth
  • client_secret: String - Segreto client OAuth
  • redirect_uri: String - URI di reindirizzamento OAuth (es. http://localhost:3080/api/mcp/${serverName}/oauth/callback)
  • scope: String - Scope OAuth (separati da spazi)
• Sottochiavi opzionali:
  • grant_types_supported: Array di Stringhe - Tipi di grant supportati (predefinito a ["authorization_code", "refresh_token"])
  • token_endpoint_auth_methods_supported: Array of Strings - Metodi di autenticazione dell'endpoint del token supportati (predefinito a ["client_secret_basic", "client_secret_post"])
  • token_exchange_method: String - Metodo di richiesta per lo scambio di token. Utilizzare default_post per i provider che si aspettano le credenziali client OAuth nel corpo della richiesta POST.
  • response_types_supported: Array di Stringhe - Tipi di risposta supportati (predefinito a ["code"])
  • code_challenge_methods_supported: Array di Stringhe - Metodi di code challenge PKCE supportati (predefinito a ["S256", "plain"])
  • skip_code_challenge_check: Booleano - Salta il controllo per verificare se il provider OAuth pubblicizza il supporto PKCE. Utile per provider come AWS Cognito che supportano S256 ma non lo pubblicizzano nei propri metadati. (il valore predefinito è false)
• Variabili d'ambiente: i campi URL OAuth definiti in YAML, inclusi authorization_url, token_url, redirect_uri e revocation_endpoint, possono utilizzare riferimenti ${ENV_VAR}. LibreChat risolve il valore dell'ambiente prima della convalida dell'URL. Gli URL degli endpoint OAuth gestiti dall'utente e inviati tramite l'interfaccia utente devono essere URL letterali e rifiutare i segnaposto ${ENV_VAR}.
• Esempio:

  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: Oggetto (Opzionale)
• Descrizione: Intestazioni utilizzate specificamente per le richieste del flusso OAuth. Queste intestazioni vengono impiegate durante l'autenticazione OAuth, come la registrazione dinamica del client e lo scambio di token, e non vengono inviate durante la normale comunicazione con il server MCP.
• Casi d'uso comuni:
  • Aggiunta dell'autenticazione agli endpoint di registrazione client dinamica, come Authorization: Bearer ${DCR_API_KEY}
  • Inclusione di intestazioni personalizzate specifiche del provider richieste per i flussi OAuth
  • Impostazione degli header necessari per gli endpoint dei token OAuth
• Differenze chiave rispetto a headers:
  • headers: Inviati con le normali richieste al server MCP dopo il completamento dell'autenticazione
  • oauth_headers: Inviato solo durante i flussi di autenticazione OAuth
• Esempio:

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

startup

• Tipo: Booleano (Opzionale)
• Descrizione: Se impostato su false, questo server MCP non verrà connesso all'avvio dell'applicazione. Ciò è utile per i server che richiedono l'input o la configurazione dell'utente prima della connessione, o per i casi in cui si desidera controllare quando il server viene inizializzato.
• Valore predefinito: true
• Esempio:

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

Note

• Inferenza del tipo:
  • Se type viene omesso:
    • Se url è specificato e inizia con http:// o https://, type è impostato per impostazione predefinita su sse.
    • Se url è specificato e inizia con ws:// o wss://, type è impostato come websocket per impostazione predefinita.
    • Se command è specificato, type è impostato come stdio per impostazione predefinita.
• Tipi di connessione:
  • stdio: Avvia un server MCP come processo figlio e comunica tramite input/output standard.
  • websocket: Si connette a un server MCP esterno tramite WebSocket.
  • sse: Si connette a un server MCP esterno tramite Server-Sent Events (SSE).
  • streamable-http: Si connette a un server MCP esterno tramite HTTP con supporto per lo streaming delle risposte.
• Indirizzi Interni/Locali:
  • Importante: I server MCP che utilizzano indirizzi IP interni (ad esempio, 172.24.1.165, 192.168.1.100) o domini locali (ad esempio, mcp-server, host.docker.internal) devono essere esplicitamente autorizzati. Utilizza mcpSettings.allowedAddresses per servizi host:porta privati specifici quando desideri che le destinazioni pubbliche rimangano raggiungibili, oppure mcpSettings.allowedDomains quando desideri una whitelist rigorosa.
  • Vedi MCP Settings per i dettagli sulla configurazione.

Esempi

Configurazione con indirizzi interni

Quando si utilizzano server MCP interni/locali e non è necessaria una whitelist di domini rigorosa, configurare mcpSettings.allowedAddresses con l'host e la porta esatti:

# 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

Server 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

Server MCP sse

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

Server MCP websocket

myWebSocketServer:
  url: ws://localhost:8080

Server 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}'

Server MCP con campi utente dinamici

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}'

Server MCP con credenziali per utente tramite 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 per ulteriori informazioni sull'inizializzazione del server basata su interfaccia utente.

Server MCP con icona personalizzata

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

Server MCP con autenticazione 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'

Server MCP con Istruzioni del Server

# 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

Server MCP abilitato per 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

Variabili d'ambiente correlate (Opzionale):

# 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

Importazione delle configurazioni del server MCP

Le configurazioni mcpServers consentono a LibreChat di interagire dinamicamente con vari server MCP, che possono eseguire attività specializzate o fornire funzionalità specifiche all'interno dell'applicazione. Questo approccio modulare facilita l'estensione delle capacità dell'applicazione semplicemente aggiungendo o modificando le configurazioni del server.

Informazioni aggiuntive

• Comportamento predefinito:
  • L'inizializzazione avviene all'avvio e l'app deve essere riavviata affinché le modifiche abbiano effetto.
  • Se vengono specificati sia url che command, il type deve essere definito esplicitamente per evitare ambiguità.
• Supporto Multi-Utente:
  • MCPManager ora supporta connessioni distinte a livello utente e a livello app, consentendo una corretta gestione delle connessioni per ogni utente.
  • Le connessioni degli utenti vengono tracciate e gestite separatamente, con una corretta configurazione e pulizia.
  • Usa segnaposto dinamici per i campi utente in intestazioni, URL e variabili d'ambiente:
    • {{LIBRECHAT_USER_ID}} - Identificativo univoco dell'utente
    • {{LIBRECHAT_USER_EMAIL}} - Indirizzo email dell'utente
    • {{LIBRECHAT_USER_USERNAME}} - Nome utente dell'utente
    • {{LIBRECHAT_USER_ROLE}} - Ruolo dell'utente (es. "user", "admin")
    • E molti altri campi (vedi la sezione headers per l'elenco completo)
• Gestione dell'inattività dell'utente:
  • Le connessioni degli utenti vengono monitorate per verificarne l'attività e verranno disconnesse dopo 15 minuti di inattività.
• Variabili d'ambiente:
  • In env (per il tipo stdio): Utile per impostare specifici ambienti di runtime o configurazioni richieste dal processo del server MCP.
  • In headers (per i tipi sse e streamable-http): Utilizza la sintassi ${ENV_VAR} per fare riferimento alle variabili d'ambiente nei valori delle intestazioni.
• Campi utente dinamici:
  • I segnaposto del campo utente vengono sostituiti in fase di esecuzione con le informazioni dell'utente autenticato.
  • Sono disponibili solo i campi non sensibili (password e altri dati sensibili sono esclusi)
  • I campi mancanti vengono impostati come stringhe vuote per impostazione predefinita
  • I campi booleani vengono convertiti in rappresentazioni stringa ("true" o "false")
• Gestione degli errori (stderr):
  • La configurazione di stderr ti consente di gestire il modo in cui vengono gestiti i messaggi di errore dal processo del server MCP. L'impostazione predefinita "inherit" significa che gli errori verranno stampati nello stderr del processo padre.
• Istruzioni del Server:
  • Le istruzioni vengono iniettate automaticamente nel messaggio di sistema dell'agente quando vengono utilizzati gli strumenti del server MCP.
  • Le Custom instructions (valori stringa) hanno la precedenza sulle istruzioni fornite dal server
  • Più server MCP possono contribuire ciascuno con le proprie istruzioni al contesto dell'agente
  • Le istruzioni sono incluse solo quando gli strumenti del server MCP corrispondente sono effettivamente disponibili per l'agente
• Autenticazione OAuth:
  • Il flusso OAuth2 è supportato per un'autenticazione sicura con i server MCP
  • Agli utenti verrà richiesto di autenticarsi tramite OAuth prima che il server MCP possa essere utilizzato

Riferimenti

• Documentazione del Model Context Protocol (MCP)
• Specifiche dei trasporti MCP
• Node.js child_process.spawn

Configurando correttamente i mcpServers nel tuo librechat.yaml, puoi migliorare le funzionalità di LibreChat e integrare strumenti e servizi personalizzati senza problemi.