Struktur des MCP Servers Objekts

Beispiel

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

Schlüssel:

Subkeys

title

• Typ: String (Optional)
• Beschreibung: Benutzerdefinierter Anzeigename für den MCP Server in der Benutzeroberfläche. Falls nicht angegeben, wird der Schlüsselname des Servers verwendet.
• Beispiel:

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

description

• Typ: String (Optional)
• Beschreibung: Beschreibung des MCP-Servers, die in der Benutzeroberfläche angezeigt wird, um Benutzern zu helfen, dessen Zweck und Funktionen zu verstehen.
• Beispiel:

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

type

• Typ: String
• Beschreibung: Legt den Verbindungstyp zum MCP Server fest. Gültige Optionen sind "stdio", "websocket", "streamable-http" oder "sse".
• Standardwert: Wird basierend auf dem Vorhandensein und Format von url oder command bestimmt.

command

• Typ: String
• Beschreibung: (Für den Typ stdio) Der Befehl oder die ausführbare Datei, die ausgeführt werden soll, um den MCP Server zu starten.

args

• Typ: Array von Strings
• Beschreibung: (Für den stdio-Typ) Befehlszeilenargumente, die an den command übergeben werden sollen.

url

• Typ: String
• Beschreibung: (Für den Typ websocket, streamable-http oder sse) Die URL, um eine Verbindung zum MCP Server herzustellen. Unterstützt dynamische Platzhalter für Benutzerfelder ({{LIBRECHAT_USER_*}}) und die Ersetzung von Umgebungsvariablen (${ENV_VAR}).
• Hinweise:
  • Für den Typ sse muss die URL mit http:// oder https:// beginnen.
  • Für den Typ streamable-http muss die URL mit http:// oder https:// beginnen.
  • Für den Typ websocket muss die URL mit ws:// oder wss:// beginnen.

proxy

• Typ: String (Optional, für sse und streamable-http Typen)
• Beschreibung: Ausgehende Proxy-URL für diesen entfernten MCP-Server. Der Wert kann Umgebungsvariablen mit ${ENV_VAR} referenzieren.
• Unterstützte Protokolle: http://, https://, socks:// und socks5://
• Sicherheitshinweis: proxy wird vom Administrator gesteuert. Es löst Umgebungsvariablen auf, löst jedoch keine benutzergesteuerten Platzhalter wie {{LIBRECHAT_USER_ID}} oder customUserVars auf.
• Beispiel:

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

headers

• Typ: Objekt (Optional, für sse und streamable-http Typen)
• Beschreibung: Benutzerdefinierte Header, die mit der Anfrage gesendet werden. Unterstützt verschiedene Platzhaltertypen für die dynamische Wertersetzung.
• Platzhalter-Unterstützung:
  • {{LIBRECHAT_USER_ID}}: Wird durch die ID des aktuellen Benutzers ersetzt, was die Unterstützung für mehrere Benutzer ermöglicht.
  • {{LIBRECHAT_USER_*}}: Dynamische Platzhalter für Benutzerfelder. Ersetzen Sie * durch die GROSSGESCHRIEBENE Version eines beliebigen zulässigen Feldes.
  • {{LIBRECHAT_OPENID_*}}: OpenID-Token-/Sitzungs-Platzhalter für in YAML definierte Server.
  • {{LIBRECHAT_GRAPH_*}}: Microsoft Graph-Token-Platzhalter für in YAML definierte Server.
  • {{LIBRECHAT_BODY_*}}: Platzhalter für den Request-Body bei YAML-definierten Servern, wie zum Beispiel die aktuelle conversationId, parentMessageId oder messageId.
  • {{CUSTOM_VARIABLE_NAME}}: Wird durch den vom Benutzer bereitgestellten Wert für eine in customUserVars definierte Variable ersetzt (z. B. {{MY_API_KEY}}).
  • ${ENV_VAR}: Wird durch den Wert der Umgebungsvariablen {{ENV_VAR}} ersetzt.

Verfügbare Platzhalter für Benutzerfelder:

Hinweis: Fehlende Felder werden durch leere Zeichenfolgen ersetzt.

{{LIBRECHAT_BODY_*}} Platzhalter sind auf den Request begrenzt (request-scoped). LibreChat erstellt die MCP-Verbindung für den aktiven Lauf, verwendet sie für Tool-Aufrufe innerhalb dieses Laufs wieder und bereinigt sie, wenn der Request endet. Request-begrenzte Server sind vom persistenten Tool-Cache ausgeschlossen, sodass anfragespezifische Header und URLs nicht außerhalb des aktiven Laufs wiederverwendet werden. {{LIBRECHAT_USER_*}}, {{LIBRECHAT_OPENID_*}} und {{LIBRECHAT_GRAPH_*}} Platzhalter machen den Server weiterhin benutzerbezogen (user-scoped), aber HTTP-Transporte aktualisieren aufgelöste Header vor jedem Tool-Aufruf, ohne dabei selbst eine erneute Verbindung zu erzwingen.

• Beispiel:

  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

• Typ: Objekt (Optional, für sse und streamable-http Typen)

• Beschreibung: Konfiguration der API-Schlüssel-Authentifizierung für den MCP-Server. Bietet eine strukturierte Möglichkeit zur Konfiguration der API-Schlüssel-basierten Authentifizierung.

• Untergeordnete Schlüssel:

  • source: String – Woher der API-Schlüssel stammt. Optionen:
    • "admin": API-Schlüssel wird vom Administrator konfiguriert (in Umgebungsvariablen oder der Konfiguration)
    • "user": API-Schlüssel wird vom Benutzer über die UI bereitgestellt
  • authorization_type: String - Wie der API-Schlüssel in Anfragen gesendet wird. Optionen:
    • "bearer": Wird als Authorization: Bearer <key> gesendet
    • "basic": Wird als Authorization: Basic <key> gesendet
    • "custom": Wird in einem benutzerdefinierten Header gesendet (erfordert custom_header)
  • custom_header: String - (Erforderlich, wenn authorization_type auf "custom" gesetzt ist) Der Header-Name, der für den API-Schlüssel verwendet werden soll

• Beispiel:

  # 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

• Typ: String (Optional)
• Beschreibung: Definiert das Anzeige-Icon des Tools, das im Tool-Auswahldialog angezeigt wird.

chatMenu

• Typ: Boolean (Optional)
• Beschreibung: Wenn auf false gesetzt, wird der MCP-Server aus dem Dropdown-Menü des Chatbereichs (MCPSelect) ausgeschlossen, um einen schnellen und einfachen Zugriff zu ermöglichen.
• Standardwert: true (Der MCP-Server wird im Dropdown-Menü des Chatbereichs enthalten sein)

serverInstructions

• Typ: Boolean oder String (Optional)

• Beschreibung: Steuert, wie MCP-Server-Anweisungen in den Agenten-Kontext eingefügt werden. Server-Anweisungen bieten eine allgemeine Nutzungsanleitung für den gesamten MCP-Server und ergänzen die Beschreibungen der einzelnen Tools.

• Optionen:

  • undefined (Standard): Es sind keine Anweisungen enthalten
  • true: Verwende die vom Server bereitgestellten Anweisungen (falls verfügbar) – ideal für gut dokumentierte Server mit umfassender Anleitung
  • false: Anweisungen explizit deaktivieren – nützlich, um Kontext-Token zu sparen oder wenn Tools selbsterklärend sind
  • string: Verwenden Sie benutzerdefinierte Anweisungen (überschreiben die vom Server bereitgestellten) – am besten geeignet für anwendungsspezifische Workflows oder wenn die Server-Anweisungen nicht ausreichen

• Standardwert: undefined (keine Anweisungen enthalten)

• Hinweise:

  • Anweisungen werden automatisch eingefügt, wenn serverInstructions konfiguriert ist und die Tools des Servers für den Agenten verfügbar sind.
  • Mehrere Server können jeweils Anweisungen zum Agent-Kontext beitragen

• Beispiel:

  # 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

• Typ: Objekt (Optional, nur stdio-Typ)
• Beschreibung: Umgebungsvariablen, die beim Starten des Prozesses verwendet werden sollen.
• Platzhalter-Unterstützung:
  • {{LIBRECHAT_USER_ID}}: Wird durch die ID des aktuellen Benutzers ersetzt.
  • {{LIBRECHAT_USER_*}}: Dynamische Platzhalter für Benutzerfelder (z. B. {{LIBRECHAT_USER_EMAIL}}).
  • {{CUSTOM_VARIABLE_NAME}}: Wird durch den vom Benutzer bereitgestellten Wert für eine in customUserVars definierte Variable ersetzt (z. B. {{MY_API_KEY}}).
  • ${ENV_VAR}: Wird durch den Wert der serverseitigen Umgebungsvariablen {{ENV_VAR}} ersetzt.

timeout

• Typ: Ganzzahl (Optional)
• Beschreibung: Timeout in Millisekunden für MCP Server-Anfragen. Muss eine nicht-negative Ganzzahl sein.
• Standardwert: 30000 (30 Sekunden)

initTimeout

• Typ: Ganzzahl (Optional)
• Beschreibung: Timeout in Millisekunden für die Initialisierung des MCP-Servers. Muss eine nicht-negative Ganzzahl sein.
• Standardwert: 10000 (10 Sekunden)

requiresOAuth

• Typ: Boolean (Optional, nur für Remote-Transports: sse, streamable-http, websocket)
• Beschreibung: Ob dieser Server eine OAuth-Authentifizierung erfordert. Falls nicht angegeben, wird dies während des Serverstarts automatisch erkannt. Obwohl optional, ist es am besten, diesen Wert explizit festzulegen, wenn Sie wissen, ob der Server OAuth erfordert oder nicht.
• Standardwert: Automatisch erkannt, falls nicht angegeben
• Hinweise:
  • Gilt für Remote-Transports (URL-basiert): sse, streamable-http und websocket. Dies hat keine Auswirkungen auf stdio-Server, da diese keine URL zur Authentifizierung besitzen.
  • Die automatische Erkennung erfolgt während des Serverstarts, was die Initialisierungszeit verlängern kann.
  • Die explizite Konfiguration verbessert die Startleistung, da die Erkennung übersprungen wird.
  • Setzen Sie requiresOAuth: false für Server, die nur durch einen statischen Authorization-Header (z. B. einen Bearer-API-Schlüssel) geschützt sind. Die automatische Erkennung prüft den Server ohne Ihre konfigurierten Header; daher kann ein Server, der mit 401 und einer WWW-Authenticate: Bearer-Challenge antwortet, fälschlicherweise als OAuth-geschützt eingestuft werden. Dieses Flag umgeht diese Prüfung und ermöglicht es Ihrem statischen Header, die Verbindung normal zu authentifizieren.
  • Funktioniert mit MCP OAuth Umgebungsvariablen (MCP_OAUTH_ON_AUTH_ERROR, MCP_OAUTH_DETECTION_TIMEOUT, MCP_OAUTH_HANDLING_TIMEOUT, MCP_OAUTH_FLOW_TTL) für ein verbessertes Verbindungsmanagement

stderr

• Typ: String oder Integer (Optional, nur stdio-Typ)
• Beschreibung: Wie mit stderr des Kindprozesses umgegangen werden soll. Dies entspricht der Semantik von Nodes child_process.spawn. Gültige String-Werte: "pipe", "ignore", "inherit". Alternativ kann eine nicht-negative Ganzzahl als Dateideskriptor verwendet werden.
• Standardwert: "inherit" (Nachrichten an stderr werden an das stderr des übergeordneten Prozesses ausgegeben).

customUserVars

• Typ: Objekt (Optional)
• Beschreibung: Definiert benutzerdefinierte Variablen, die Benutzer für diesen MCP-Server festlegen können. Dies ermöglicht es Administratoren, Variablen (z. B. API-Schlüssel, URLs) anzugeben, die jeder Benutzer individuell konfigurieren muss. Diese vom Benutzer bereitgestellten Werte können dann in headers oder env-Konfigurationen verwendet werden. Server mit customUserVars werden automatisch von Verbindungen auf App-Ebene ausgeschlossen, wodurch sichergestellt wird, dass benutzerspezifische Anmeldeinformationen immer zur Laufzeit aufgelöst werden.
• Struktur:
  • Das customUserVars-Objekt enthält Schlüssel, wobei jeder Schlüssel einen Variablennamen darstellt (z. B. MY_API_KEY). Dieser Name wird in Platzhaltern wie {{MY_API_KEY}} verwendet.
  • Jeder Variablenname ist ein Objekt mit den folgenden Unterschlüsseln:
    • title: String (Erforderlich) - Ein benutzerfreundlicher Titel für die Variable, der in der Konfigurations-UI angezeigt wird.
    • 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 (Optional) – Steuert, ob der Wert als Geheimnis behandelt und in der UI maskiert wird. Standardmäßig wird das maskierte/geheime Verhalten angewendet, wenn dies weggelassen wird; setzen Sie es auf false für nicht geheime Felder wie Projekt-IDs oder Basis-URLs.
• Verwendung in headers und env:
  • Sobald diese Variablen unter customUserVars definiert wurden, können sie in den Abschnitten headers (für die Typen sse und streamable-http) oder env (für den Typ stdio) unter Verwendung der Syntax {{VARIABLE_NAME}} referenziert werden.
  • Benutzer geben diese Werte über die UI ein. Auf diese Einstellungen kann auf zwei Arten zugegriffen werden:
    • Von der Assistant-Chat-Eingabe: Wenn Sie MCP-Tools für einen Assistant auswählen, erscheint ein Einstellungssymbol neben konfigurierbaren MCP-Servern im Dropdown-Menü zur Tool-Auswahl. Ein Klick auf dieses Symbol öffnet ein Dialogfeld zur Verwaltung der Anmeldedaten für diesen Server.
    • Über das Einstellungsmenü: Ein dedizierter Bereich "MCP Settings" im rechten Bedienfeld listet alle MCP-Server mit definierbaren benutzerdefinierten Variablen auf. Benutzer können auf einen Server klicken, um den Konfigurationsdialog zu öffnen und ihre Anmeldedaten für diesen spezifischen MCP-Server festzulegen oder zu aktualisieren.
  • Diese vom Benutzer bereitgestellten Werte werden sicher gespeichert, dem jeweiligen Benutzer sowie dem spezifischen MCP Server zugeordnet und zur Laufzeit ersetzt.
• Beispiel:

  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

  Verwendung in headers:

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

  Verwendung in env (für den Typ stdio):

  env:
    API_KEY: '{{MY_SERVICE_API_KEY}}'

obo

• Typ: Objekt (Optional, nur für sse und streamable-http Typen)
• Beschreibung: Konfiguriert den OAuth 2.0 On-Behalf-Of-Token-Austausch für einen MCP Server. LibreChat tauscht das OpenID-Zugriffstoken des angemeldeten Benutzers gegen ein delegiertes Downstream-Token mit den konfigurierten Scopes aus und leitet dieses Token dann als Authorization: Bearer ...-Header an den MCP Server weiter.
• Erforderliche Unter-Keys:
  • scopes: String - Nicht leere Scopes, die für den nachgelagerten Token-Austausch angefordert werden.
• Validierung:
  • obo ist nur für sse und streamable-http MCP-Server gültig.
  • obo wird für stdio- und websocket-Server abgelehnt.
  • Benutzer benötigen die MCP_SERVERS.CONFIGURE_OBO Rollenberechtigung, um dieses Feld zu konfigurieren. Initialisieren Sie es mit interface.mcpServers.configureObo oder verwalten Sie es über das Admin-Panel.
• Voraussetzungen:
  • Die OpenID-Authentifizierung muss mit wiederverwendbaren Zugriffstokens konfiguriert werden.
  • Ihr Identitätsanbieter und die nachgelagerte Anwendung müssen den angeforderten delegierten Bereich (delegated scope) zulassen.
• Beispiel:

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

Siehe OpenID Connect Token Reuse und SharePoint Integration für Informationen zur Wiederverwendung von Token und zur Einrichtung delegierter Token.

oauth

• Typ: Objekt (Optional)
• Beschreibung: OAuth2-Konfiguration für die Authentifizierung mit dem MCP-Server. Wenn diese konfiguriert ist, werden Benutzer aufgefordert, sich über einen OAuth-Flow zu authentifizieren, bevor der MCP-Server verwendet werden kann. Wenn keine Client-ID und kein Client-Secret angegeben sind, wird die dynamische Client-Registrierung (DCR) verwendet.
• Erforderliche Unter-Keys:
  • authorization_url: String - Die OAuth-Autorisierungs-Endpoint-URL
  • token_url: String - Die URL des OAuth-Token-Endpunkts
  • client_id: String - OAuth-Client-Identifikator
  • client_secret: String - OAuth-Client-Secret
  • redirect_uri: String - OAuth-Redirect-URI (z. B. http://localhost:3080/api/mcp/${serverName}/oauth/callback)
  • scope: String - OAuth-Scopes (durch Leerzeichen getrennt)
• Optionale Unter-Keys:
  • grant_types_supported: Array von Strings - Unterstützte Grant-Typen (Standardwert ist ["authorization_code", "refresh_token"])
  • token_endpoint_auth_methods_supported: Array of Strings – Unterstützte Authentifizierungsmethoden für den Token-Endpunkt (Standardwert ist ["client_secret_basic", "client_secret_post"])
  • token_exchange_method: String - Methode für die Token-Austausch-Anfrage. Verwenden Sie default_post für Anbieter, die die OAuth-Client-Anmeldeinformationen im POST-Body erwarten.
  • response_types_supported: Array von Strings - Unterstützte Antworttypen (Standardwert ist ["code"])
  • code_challenge_methods_supported: Array of Strings - Unterstützte PKCE-Code-Challenge-Methoden (Standardwert ist ["S256", "plain"])
  • skip_code_challenge_check: Boolean - Überspringt die Überprüfung, ob der OAuth-Anbieter PKCE-Unterstützung ankündigt. Nützlich für Anbieter wie AWS Cognito, die S256 unterstützen, dies aber nicht in ihren Metadaten angeben. (Standardwert ist false)
• Umgebungsvariablen: In YAML definierten OAuth-URL-Felder, einschließlich authorization_url, token_url, redirect_uri und revocation_endpoint, können ${ENV_VAR}-Referenzen verwenden. LibreChat löst den Umgebungswert vor der URL-Validierung auf. Vom Benutzer verwaltete OAuth-Endpunkt-URLs, die über die Benutzeroberfläche übermittelt werden, müssen literale URLs sein und lehnen ${ENV_VAR}-Platzhalter ab.
• Beispiel:

  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

• Typ: Objekt (Optional)
• Beschreibung: Header, die speziell für OAuth-Flow-Anfragen verwendet werden. Diese Header werden während der OAuth-Authentifizierung, wie z. B. bei der dynamischen Client-Registrierung und dem Token-Austausch, verwendet und nicht während der regulären MCP-Server-Kommunikation gesendet.
• Häufige Anwendungsfälle:
  • Hinzufügen einer Authentifizierung zu dynamischen Client-Registrierungs-endpoints, wie z. B. Authorization: Bearer ${DCR_API_KEY}
  • Einschließlich benutzerdefinierter anbieterspezifischer Header, die für OAuth-Flows erforderlich sind
  • Festlegen der für OAuth-Token-Endpunkte erforderlichen Header
• Hauptunterschiede zu headers:
  • headers: Werden nach Abschluss der Authentifizierung mit regulären MCP-Serveranfragen gesendet
  • oauth_headers: Wird nur während OAuth-Authentifizierungsabläufen gesendet
• Beispiel:

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

startup

• Typ: Boolean (Optional)
• Beschreibung: Wenn dies auf false gesetzt ist, wird dieser MCP Server nicht beim Anwendungsstart verbunden. Dies ist nützlich für Server, die vor dem Verbinden eine Benutzereingabe oder Konfiguration erfordern, oder für Fälle, in denen Sie steuern möchten, wann der Server initialisiert wird.
• Standardwert: true
• Beispiel:

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

Hinweise

• Typinferenz:
  • Wenn type weggelassen wird:
    • Wenn url angegeben ist und mit http:// oder https:// beginnt, ist der Standardwert für type sse.
    • Wenn url angegeben ist und mit ws:// oder wss:// beginnt, wird type standardmäßig auf websocket gesetzt.
    • Wenn command angegeben ist, ist der Standardwert für type stdio.
• Verbindungstypen:
  • stdio: Startet einen MCP-Server als untergeordneten Prozess und kommuniziert über die Standard-Ein-/Ausgabe.
  • websocket: Verbindet sich über WebSocket mit einem externen MCP Server.
  • sse: Verbindet sich über Server-Sent Events (SSE) mit einem externen MCP-Server.
  • streamable-http: Stellt eine Verbindung zu einem externen MCP-Server über HTTP her, mit Unterstützung für Streaming-Antworten.
• Interne/Lokale Adressen:
  • Wichtig: MCP-Server, die interne IP-Adressen (z. B. 172.24.1.165, 192.168.1.100) oder lokale Domains (z. B. mcp-server, host.docker.internal) verwenden, müssen explizit erlaubt werden. Verwenden Sie mcpSettings.allowedAddresses für spezifische private Host:Port-Dienste, wenn öffentliche Ziele weiterhin erreichbar bleiben sollen, oder mcpSettings.allowedDomains, wenn Sie eine strikte Whitelist wünschen.
  • Siehe MCP Settings für Konfigurationsdetails.

Beispiele

Konfiguration mit internen Adressen

Wenn Sie interne/lokale MCP-Server verwenden und keine strikte Domain-Whitelist erforderlich ist, konfigurieren Sie mcpSettings.allowedAddresses mit dem exakten Host und Port:

# 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

stdio MCP Server

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

sse MCP Server

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

websocket MCP Server

myWebSocketServer:
  url: ws://localhost:8080

streamable-http MCP Server

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

MCP Server mit dynamischen Benutzerfeldern

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

MCP-Server mit benutzerspezifischen Anmeldedaten über 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

HINWEIS Siehe MCP Server Initialization für weitere Informationen zur UI-basierten Server-Initialisierung.

MCP Server mit benutzerdefiniertem Icon

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

MCP Server mit OAuth-Authentifizierung

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'

MCP Server mit Server-Anweisungen

# 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

OAuth-fähiger MCP-Server (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

Zugehörige Umgebungsvariablen (Optional):

# 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

Importieren von MCP Server-Konfigurationen

Die mcpServers-Konfigurationen ermöglichen es LibreChat, dynamisch mit verschiedenen MCP-Servern zu interagieren, die spezialisierte Aufgaben ausführen oder spezifische Funktionen innerhalb der Anwendung bereitstellen können. Dieser modulare Ansatz erleichtert die Erweiterung der Anwendungsfunktionen durch einfaches Hinzufügen oder Ändern von Serverkonfigurationen.

Zusätzliche Informationen

• Standardverhalten:
  • Die Initialisierung erfolgt beim Start, und die App muss neu gestartet werden, damit Änderungen wirksam werden.
  • Wenn sowohl url als auch command angegeben sind, muss der type explizit definiert werden, um Mehrdeutigkeiten zu vermeiden.
• Multi-User-Unterstützung:
  • Der MCPManager unterstützt jetzt separate Verbindungen auf Benutzer- und App-Ebene, was eine ordnungsgemäße Verbindungsverwaltung pro Benutzer ermöglicht.
  • Benutzerverbindungen werden separat nachverfolgt und verwaltet, mit ordnungsgemäßer Einrichtung und Bereinigung.
  • Verwenden Sie dynamische Platzhalter für Benutzerfelder in Headern, URLs und Umgebungsvariablen:
    • {{LIBRECHAT_USER_ID}} - Eindeutige Kennung des Benutzers
    • {{LIBRECHAT_USER_EMAIL}} - E-Mail-Adresse des Benutzers
    • {{LIBRECHAT_USER_USERNAME}} - Benutzername des Benutzers
    • {{LIBRECHAT_USER_ROLE}} - Rolle des Benutzers (z. B. "user", "admin")
    • Und viele weitere Felder (siehe Abschnitt „Headers“ für eine vollständige Liste)
• Verwaltung der Benutzerinaktivität:
  • Benutzerverbindungen werden auf Aktivität überwacht und nach 15 Minuten Inaktivität getrennt.
• Umgebungsvariablen:
  • In env (für den Typ stdio): Nützlich zum Einrichten spezifischer Laufzeitumgebungen oder Konfigurationen, die für den MCP Server-Prozess erforderlich sind.
  • In headers (für sse- und streamable-http-Typen): Verwenden Sie die ${ENV_VAR}-Syntax, um auf Umgebungsvariablen in Header-Werten zu verweisen.
• Dynamische Benutzerfelder:
  • Benutzerfeld-Platzhalter werden zur Laufzeit durch die Informationen des authentifizierten Benutzers ersetzt.
  • Nur nicht sensible Felder sind verfügbar (Passwörter und andere sensible Daten sind ausgeschlossen)
  • Fehlende Felder werden standardmäßig als leere Strings behandelt
  • Boolesche Felder werden in String-Repräsentationen ("true" oder "false") konvertiert.
• Fehlerbehandlung (stderr):
  • Die Konfiguration von stderr ermöglicht es Ihnen zu verwalten, wie Fehlermeldungen des MCP Server-Prozesses behandelt werden. Die Standardeinstellung "inherit" bedeutet, dass die Fehler an den stderr des übergeordneten Prozesses ausgegeben werden.
• Server-Anweisungen:
  • Anweisungen werden automatisch in die Systemnachricht des Agenten eingefügt, wenn MCP Server-Tools verwendet werden.
  • Benutzerdefinierte Anweisungen (String-Werte) haben Vorrang vor den vom Server bereitgestellten Anweisungen
  • Mehrere MCP-Server können jeweils ihre eigenen Anweisungen zum Agent-Kontext beitragen
  • Anweisungen werden nur dann einbezogen, wenn die Tools des entsprechenden MCP-Servers tatsächlich für den Agenten verfügbar sind.
• OAuth-Authentifizierung:
  • Der OAuth2-Ablauf wird für die sichere Authentifizierung mit MCP-Servern unterstützt.
  • Benutzer werden aufgefordert, sich über OAuth zu authentifizieren, bevor der MCP Server verwendet werden kann.

Referenzen

• Dokumentation zum Model Context Protocol (MCP)
• MCP Transports Specification
• Node.js child_process.spawn

Durch die ordnungsgemäße Konfiguration der mcpServers in Ihrer librechat.yaml können Sie die Funktionalität von LibreChat erweitern und benutzerdefinierte Tools sowie Dienste nahtlos integrieren.