Objectstructuur van MCP Servers

Voorbeeld

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

Sleutel:

Subkeys

title

• Type: String (Optioneel)
• Beschrijving: Aangepaste weergavenaam voor de MCP server in de UI. Indien niet opgegeven, wordt de naam van de serversleutel gebruikt.
• Voorbeeld:

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

description

• Type: String (Optioneel)
• Beschrijving: Beschrijving van de MCP server, die in de UI wordt weergegeven om gebruikers te helpen het doel en de mogelijkheden ervan te begrijpen.
• Voorbeeld:

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

type

• Type: String
• Beschrijving: Specificeert het verbindingstype naar de MCP server. Geldige opties zijn "stdio", "websocket", "streamable-http", of "sse".
• Standaardwaarde: Bepaald op basis van de aanwezigheid en het formaat van url of command.

command

• Type: String
• Beschrijving: (Voor het stdio type) Het commando of uitvoerbaar bestand dat moet worden uitgevoerd om de MCP server te starten.

args

• Type: Array of Strings
• Beschrijving: (Voor stdio type) Opdrachtregelargumenten die aan het command moeten worden meegegeven.

url

• Type: String
• Beschrijving: (Voor websocket, streamable-http of sse type) De URL om verbinding te maken met de MCP server. Ondersteunt dynamische placeholders voor gebruikersvelden ({{LIBRECHAT_USER_*}}) en vervanging van omgevingsvariabelen (${ENV_VAR}).
• Opmerkingen:
  • Voor het type sse moet de URL beginnen met http:// of https://.
  • Voor het type streamable-http moet de URL beginnen met http:// of https://.
  • Voor het type websocket moet de URL beginnen met ws:// of wss://.

proxy

• Type: String (Optioneel, voor sse en streamable-http types)
• Beschrijving: Outbound proxy-URL voor deze externe MCP-server. De waarde kan verwijzen naar omgevingsvariabelen met ${ENV_VAR}.
• Ondersteunde protocollen: http://, https://, socks:// en socks5://
• Beveiligingsopmerking: proxy wordt beheerd door de beheerder. Het lost omgevingsvariabelen op, maar lost geen door de gebruiker beheerde tijdelijke aanduidingen zoals {{LIBRECHAT_USER_ID}} of customUserVars op.
• Voorbeeld:

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

headers

• Type: Object (Optioneel, voor sse en streamable-http types)
• Beschrijving: Aangepaste headers om mee te sturen met het verzoek. Ondersteunt verschillende typen tijdelijke aanduidingen voor dynamische waardesubstitutie.
• Ondersteuning voor tijdelijke aanduidingen (Placeholders):
  • {{LIBRECHAT_USER_ID}}: Wordt vervangen door de ID van de huidige gebruiker, wat ondersteuning voor meerdere gebruikers mogelijk maakt.
  • {{LIBRECHAT_USER_*}}: Dynamische placeholders voor gebruikersvelden. Vervang * door de HOOFDLETTER-versie van elk toegestaan veld.
  • {{LIBRECHAT_OPENID_*}}: OpenID token/sessie-placeholders voor in YAML gedefinieerde servers.
  • {{LIBRECHAT_GRAPH_*}}: Microsoft Graph token-placeholders voor in YAML gedefinieerde servers.
  • {{LIBRECHAT_BODY_*}}: Request body placeholders voor in YAML gedefinieerde servers, zoals de huidige conversationId, parentMessageId of messageId.
  • {{CUSTOM_VARIABLE_NAME}}: Wordt vervangen door de waarde die door de gebruiker is opgegeven voor een variabele gedefinieerd in customUserVars (bijv. {{MY_API_KEY}}).
  • ${ENV_VAR}: Zal worden vervangen door de waarde van de omgevingsvariabele {{ENV_VAR}}.

Beschikbare tijdelijke aanduidingen voor gebruikersvelden:

Let op: Ontbrekende velden worden vervangen door lege strings.

{{LIBRECHAT_BODY_*}} placeholders zijn request-scoped. LibreChat creëert de MCP-verbinding voor de actieve run, hergebruikt deze voor tool-aanroepen binnen die run en ruimt deze op wanneer het verzoek eindigt. Request-scoped servers worden uitgesloten van de persistente tool-cache, zodat verzoek-specifieke headers en URL's niet buiten de actieve run worden hergebruikt. {{LIBRECHAT_USER_*}}, {{LIBRECHAT_OPENID_*}} en {{LIBRECHAT_GRAPH_*}} placeholders maken de server nog steeds user-scoped, maar HTTP-transports verversen opgeloste headers vóór elke tool-aanroep zonder zelf een herverbinding te forceren.

• Voorbeeld:

  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

• Type: Object (Optioneel, voor sse en streamable-http types)

• Beschrijving: Configuratie van API-sleutelauthenticatie voor de MCP server. Biedt een gestructureerde manier om authenticatie op basis van API-sleutels te configureren.

• Sub-keys:

  • source: String - Waar de API-sleutel vandaan komt. Opties:
    • "admin": API-sleutel is geconfigureerd door de beheerder (in omgevingsvariabelen of config)
    • "user": API-sleutel wordt door de gebruiker verstrekt via de UI
  • authorization_type: String - Hoe de API-sleutel wordt verzonden in verzoeken. Opties:
    • "bearer": Verzonden als Authorization: Bearer <key>
    • "basic": Wordt verzonden als Authorization: Basic <key>
    • "custom": Verzonden in een aangepaste header (vereist custom_header)
  • custom_header: String - (Vereist wanneer authorization_type "custom" is) De headernaam die moet worden gebruikt voor de API-sleutel

• Voorbeeld:

  # 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

• Type: String (Optioneel)
• Beschrijving: Definieert het weergave-icoon van de tool dat wordt getoond in het dialoogvenster voor toolselectie.

chatMenu

• Type: Boolean (Optioneel)
• Beschrijving: Indien ingesteld op false, wordt de MCP server uitgesloten van de chatarea dropdown (MCPSelect) voor snelle en gemakkelijke toegang.
• Standaardwaarde: true (De MCP server wordt opgenomen in de dropdown van het chatgebied)

serverInstructions

• Type: Boolean of String (Optioneel)

• Beschrijving: Bepaalt hoe MCP server-instructies worden geïnjecteerd in de context van de agent. Server-instructies bieden gebruiksrichtlijnen op hoog niveau voor de gehele MCP server, als aanvulling op de individuele tool-beschrijvingen.

• Opties:

  • undefined (standaard): Er zijn geen instructies opgenomen
  • true: Gebruik door de server verstrekte instructies (indien beschikbaar) - ideaal voor goed gedocumenteerde servers met uitgebreide richtlijnen
  • false: Schakel instructies expliciet uit - handig om context-tokens te besparen of wanneer tools voor zichzelf spreken
  • string: Gebruik aangepaste instructies (overschrijft de door de server verstrekte instructies) - het beste voor applicatiespecifieke workflows of wanneer serverinstructies onvoldoende zijn

• Standaardwaarde: undefined (geen instructies inbegrepen)

• Opmerkingen:

  • Instructies worden automatisch geïnjecteerd wanneer serverInstructions is geconfigureerd en de tools van de server beschikbaar zijn voor de agent.
  • Meerdere servers kunnen elk instructies bijdragen aan de agent-context

• Voorbeeld:

  # 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

• Type: Object (Optioneel, alleen stdio type)
• Beschrijving: Omgevingsvariabelen die moeten worden gebruikt bij het starten van het proces.
• Ondersteuning voor tijdelijke aanduidingen (Placeholders):
  • {{LIBRECHAT_USER_ID}}: Vervangen door het ID van de huidige gebruiker.
  • {{LIBRECHAT_USER_*}}: Dynamische tijdelijke aanduidingen voor gebruikersvelden (bijv. {{LIBRECHAT_USER_EMAIL}}).
  • {{CUSTOM_VARIABLE_NAME}}: Wordt vervangen door de waarde die door de gebruiker is opgegeven voor een variabele gedefinieerd in customUserVars (bijv. {{MY_API_KEY}}).
  • ${ENV_VAR}: Vervangen door de waarde van de server-side omgevingsvariabele {{ENV_VAR}}.

timeout

• Type: Geheel getal (Optioneel)
• Beschrijving: Time-out in milliseconden voor MCP serververzoeken. Moet een niet-negatief geheel getal zijn.
• Standaardwaarde: 30000 (30 seconden)

initTimeout

• Type: Geheel getal (Optioneel)
• Beschrijving: Time-out in milliseconden voor de initialisatie van de MCP-server. Moet een niet-negatief geheel getal zijn.
• Standaardwaarde: 10000 (10 seconden)

requiresOAuth

• Type: Boolean (Optioneel, alleen voor externe transports: sse, streamable-http, websocket)
• Beschrijving: Of deze server OAuth-authenticatie vereist. Indien niet gespecificeerd, wordt dit automatisch gedetecteerd tijdens het opstarten van de server. Hoewel optioneel, is het het beste om deze waarde expliciet in te stellen als u weet of de server OAuth vereist of niet.
• Standaardwaarde: Automatisch gedetecteerd indien niet gespecificeerd
• Opmerkingen:
  • Van toepassing op remote (URL-gebaseerde) transports: sse, streamable-http en websocket. Het heeft geen effect op stdio servers, die geen URL hebben om tegen te authenticeren.
  • Auto-detectie vindt plaats tijdens het opstarten van de server, wat de initialisatietijd kan verlengen.
  • Expliciete configuratie verbetert de opstartprestaties door detectie over te slaan
  • Stel requiresOAuth: false in voor servers die alleen worden beveiligd door een statische Authorization header (bijv. een Bearer API-sleutel). Automatische detectie onderzoekt de server zonder uw geconfigureerde headers, waardoor een server die antwoordt met een 401 met een WWW-Authenticate: Bearer challenge onterecht als OAuth-beveiligd kan worden geclassificeerd; deze vlag omzeilt die controle en laat uw statische header de verbinding normaal verifiëren.
  • Werkt met MCP OAuth omgevingsvariabelen (MCP_OAUTH_ON_AUTH_ERROR, MCP_OAUTH_DETECTION_TIMEOUT, MCP_OAUTH_HANDLING_TIMEOUT, MCP_OAUTH_FLOW_TTL) voor verbeterd verbindingsbeheer

stderr

• Type: String of Integer (Optioneel, alleen stdio type)
• Beschrijving: Hoe om te gaan met stderr van het onderliggende proces. Dit komt overeen met de semantiek van Node's child_process.spawn. Geldige stringwaarden: "pipe", "ignore", "inherit". Als alternatief kan een niet-negatief geheel getal worden gebruikt als bestandsdescriptor.
• Standaardwaarde: "inherit" (berichten naar stderr worden afgedrukt naar de stderr van het bovenliggende proces).

customUserVars

• Type: Object (Optioneel)
• Beschrijving: Definieert aangepaste variabelen die gebruikers kunnen instellen voor deze MCP server. Hiermee kunnen beheerders variabelen opgeven (bijv. API-sleutels, URL's) die elke gebruiker individueel moet configureren. Deze door de gebruiker verstrekte waarden kunnen vervolgens worden gebruikt in headers of env configuratie. Servers met customUserVars worden automatisch uitgesloten van verbindingen op app-niveau, waardoor wordt gegarandeerd dat inloggegevens per gebruiker altijd tijdens runtime worden opgelost.
• Structuur:
  • Het customUserVars object bevat keys, waarbij elke key een variabelenaam vertegenwoordigt (bijv. MY_API_KEY). Deze naam wordt gebruikt in placeholders zoals {{MY_API_KEY}}.
  • Elke variabelenaam is een object met de volgende subkeys:
    • title: String (Vereist) - Een gebruiksvriendelijke titel voor de variabele, weergegeven in de configuratie-UI.
    • 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 (Optioneel) - Bepaalt of de waarde als een geheim wordt behandeld en gemaskeerd in de UI. Standaard is dit gemaskeerd/geheim wanneer weggelaten; zet op false voor niet-geheime velden zoals project-ID's of basis-URL's.
• Gebruik in headers en env:
  • Zodra deze variabelen zijn gedefinieerd onder customUserVars, kunnen ze worden verwezen in de headers (voor sse en streamable-http types) of env (voor stdio type) secties met behulp van de {{VARIABLE_NAME}} syntaxis.
  • Gebruikers verstrekken deze waarden via de UI. Deze instellingen kunnen op twee manieren worden benaderd:
    • Vanuit de chat-invoer van de assistent: Bij het selecteren van MCP tools voor een assistent verschijnt er een instellingenpictogram naast configureerbare MCP-servers in het vervolgkeuzemenu voor toolselectie. Door op dit pictogram te klikken, wordt een dialoogvenster geopend om inloggegevens voor die server te beheren.
    • Vanuit het instellingenpaneel: Een speciale "MCP Settings" sectie in het rechterpaneel bevat een lijst met alle MCP servers met definieerbare aangepaste variabelen. Gebruikers kunnen op een server klikken om het configuratiedialoogvenster te openen en hun inloggegevens voor die specifieke MCP server in te stellen of bij te werken.
  • Deze door de gebruiker verstrekte waarden worden veilig opgeslagen, gekoppeld aan de individuele gebruiker en de specifieke MCP server, en tijdens runtime vervangen.
• Voorbeeld:

  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

  Gebruik 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

• Type: Object (Optioneel, alleen voor sse en streamable-http types)
• Beschrijving: Configureert OAuth 2.0 On-Behalf-Of token-uitwisseling voor een MCP server. LibreChat wisselt het OpenID-toegangstoken van de ingelogde gebruiker in voor een gedelegeerd downstream-token met de geconfigureerde scopes, en stuurt dat token vervolgens door naar de MCP server als een Authorization: Bearer ... header.
• Vereiste subkeys:
  • scopes: String - Niet-lege scopes aangevraagd voor de downstream token-uitwisseling.
• Validatie:
  • obo is alleen geldig voor sse en streamable-http MCP servers.
  • obo wordt geweigerd voor stdio en websocket servers.
  • Gebruikers hebben de MCP_SERVERS.CONFIGURE_OBO roltoestemming nodig om dit veld te configureren. Voorzie het van een beginwaarde met interface.mcpServers.configureObo of beheer het vanuit het beheerderspaneel.
• Vereisten:
  • OpenID-authenticatie moet worden geconfigureerd met herbruikbare toegangstokens.
  • Je identiteitsprovider en downstream-applicatie moeten het gevraagde gedelegeerde bereik toestaan.
• Voorbeeld:

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

Zie OpenID Connect Token Reuse en SharePoint Integration voor gerelateerde instellingen voor token-hergebruik en gedelegeerde tokens.

oauth

• Type: Object (Optioneel)
• Beschrijving: OAuth2-configuratie voor authenticatie met de MCP server. Wanneer geconfigureerd, worden gebruikers gevraagd om te authenticeren via een OAuth-flow voordat de MCP server kan worden gebruikt. Als er geen client id & client secret worden verstrekt, zal Dynamic Client Registration (DCR) worden gebruikt.
• Vereiste subkeys:
  • authorization_url: String - De URL van het OAuth-autorisatie-endpoint
  • token_url: String - De OAuth token endpoint URL
  • client_id: String - OAuth client-identificatie
  • client_secret: String - OAuth client secret
  • redirect_uri: String - OAuth redirect URI (bijv. http://localhost:3080/api/mcp/${serverName}/oauth/callback)
  • scope: String - OAuth scopes (gescheiden door spaties)
• Optionele subkeys:
  • grant_types_supported: Array of Strings - Ondersteunde grant types (standaard ["authorization_code", "refresh_token"])
  • token_endpoint_auth_methods_supported: Array of Strings - Ondersteunde authenticatiemethoden voor het token-endpoint (standaard ingesteld op ["client_secret_basic", "client_secret_post"])
  • token_exchange_method: String - Aanvraagmethode voor tokenuitwisseling. Gebruik default_post voor providers die de OAuth-clientreferenties in de POST-body verwachten.
  • response_types_supported: Array of Strings - Ondersteunde responstypes (standaard ["code"])
  • code_challenge_methods_supported: Array van Strings - Ondersteunde PKCE code challenge methoden (standaard ["S256", "plain"])
  • skip_code_challenge_check: Boolean - Sla het controleren of de OAuth-provider PKCE-ondersteuning adverteert over. Handig voor providers zoals AWS Cognito die S256 ondersteunen, maar dit niet adverteren in hun metadata. (standaard is false)
• Omgevingsvariabelen: YAML-gedefinieerde OAuth URL-velden, inclusief authorization_url, token_url, redirect_uri en revocation_endpoint, kunnen ${ENV_VAR} referenties gebruiken. LibreChat lost de omgevingswaarde op vóór URL-validatie. Door de gebruiker beheerde OAuth endpoint URL's die via de UI worden ingediend, moeten letterlijke URL's zijn en wijzen ${ENV_VAR} placeholders af.
• Voorbeeld:

  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

• Type: Object (Optioneel)
• Beschrijving: Headers die specifiek worden gebruikt voor OAuth-stroomverzoeken. Deze headers worden gebruikt tijdens OAuth-authenticatie, zoals dynamische clientregistratie en token-uitwisseling, en worden niet verzonden tijdens reguliere MCP-servercommunicatie.
• Veelvoorkomende gebruiksscenario's:
  • Authenticatie toevoegen aan dynamic client registration endpoints, zoals Authorization: Bearer ${DCR_API_KEY}
  • Inclusief aangepaste provider-specifieke headers die vereist zijn voor OAuth-flows
  • Headers instellen die nodig zijn voor OAuth-token-endpoints
• Belangrijkste verschillen met headers:
  • headers: Wordt verzonden met reguliere MCP-serververzoeken nadat de authenticatie is voltooid
  • oauth_headers: Wordt alleen verzonden tijdens OAuth-authenticatiestromen
• Voorbeeld:

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

startup

• Type: Boolean (Optioneel)
• Beschrijving: Wanneer ingesteld op false, zal deze MCP server niet worden verbonden bij het opstarten van de applicatie. Dit is nuttig voor servers die gebruikersinvoer of configuratie vereisen voordat ze verbinding maken, of voor gevallen waarin u wilt bepalen wanneer de server wordt geïnitialiseerd.
• Standaardwaarde: true
• Voorbeeld:

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

Opmerkingen

• Type-inferentie:
  • Als type wordt weggelaten:
    • Als url is opgegeven en begint met http:// of https://, dan is de standaardwaarde voor type sse.
    • Als url is opgegeven en begint met ws:// of wss://, dan is type standaard websocket.
    • Als command is opgegeven, is de standaardwaarde voor type stdio.
• Verbindingstypen:
  • stdio: Start een MCP-server als een onderliggend proces en communiceert via standaard invoer/uitvoer.
  • websocket: Maakt verbinding met een externe MCP-server via WebSocket.
  • sse: Maakt verbinding met een externe MCP-server via Server-Sent Events (SSE).
  • streamable-http: Maakt verbinding met een externe MCP-server via HTTP met ondersteuning voor streaming-antwoorden.
• Interne/Lokale Adressen:
  • Belangrijk: MCP-servers die interne IP-adressen (bijv. 172.24.1.165, 192.168.1.100) of lokale domeinen (bijv. mcp-server, host.docker.internal) gebruiken, moeten expliciet worden toegestaan. Gebruik mcpSettings.allowedAddresses voor specifieke private host:port-services wanneer je wilt dat publieke bestemmingen bereikbaar blijven, of mcpSettings.allowedDomains wanneer je een strikte whitelist wilt hanteren.
  • Zie MCP Settings voor configuratiedetails.

Voorbeelden

Configuratie met interne adressen

Bij gebruik van interne/lokale MCP-servers en wanneer er geen strikte domein-whitelist nodig is, configureer mcpSettings.allowedAddresses met de exacte host en poort:

# 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 met dynamische gebruikersvelden

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 met per-gebruiker inloggegevens 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

LET OP Zie MCP Server Initialization voor meer informatie over UI-gebaseerde serverinitialisatie.

MCP Server met aangepast icoon

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 met OAuth-authenticatie

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 met Server Instructies

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

Gerelateerde omgevingsvariabelen (Optioneel):

# 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

MCP Server-configuraties importeren

Met de mcpServers configuraties kan LibreChat dynamisch communiceren met verschillende MCP servers, die gespecialiseerde taken kunnen uitvoeren of specifieke functionaliteiten binnen de applicatie kunnen bieden. Deze modulaire aanpak vergemakkelijkt het uitbreiden van de mogelijkheden van de applicatie door simpelweg serverconfiguraties toe te voegen of te wijzigen.

Aanvullende informatie

• Standaardgedrag:
  • Initialisatie vindt plaats bij het opstarten en de app moet opnieuw worden opgestart om wijzigingen door te voeren.
  • Als zowel url als command zijn opgegeven, moet het type expliciet worden gedefinieerd om ambiguïteit te voorkomen.
• Multi-User Support:
  • De MCPManager ondersteunt nu afzonderlijke verbindingen op gebruikersniveau en app-niveau, wat een correct beheer van verbindingen per gebruiker mogelijk maakt.
  • Gebruikersverbindingen worden afzonderlijk bijgehouden en beheerd, met een correcte totstandbrenging en opschoning.
  • Gebruik dynamische gebruikersveld-placeholders in headers, URL's en omgevingsvariabelen:
    • {{LIBRECHAT_USER_ID}} - Unieke identificatiecode van de gebruiker
    • {{LIBRECHAT_USER_EMAIL}} - E-mailadres van de gebruiker
    • {{LIBRECHAT_USER_USERNAME}} - Gebruikersnaam van de gebruiker
    • {{LIBRECHAT_USER_ROLE}} - Rol van de gebruiker (bijv. "user", "admin")
    • En nog veel meer velden (zie de sectie headers voor de volledige lijst)
• Gebruikersinactiviteitsbeheer:
  • Gebruikersverbindingen worden gecontroleerd op activiteit en worden na 15 minuten inactiviteit verbroken.
• Omgevingsvariabelen:
  • In env (voor stdio type): Handig voor het instellen van specifieke runtime-omgevingen of configuraties die vereist zijn voor het MCP serverproces.
  • In headers (voor sse en streamable-http types): Gebruik de ${ENV_VAR} syntaxis om te verwijzen naar omgevingsvariabelen in headerwaarden.
• Dynamische gebruikersvelden:
  • Gebruikersveld-placeholders worden tijdens runtime vervangen door de informatie van de geauthenticeerde gebruiker.
  • Alleen niet-gevoelige velden zijn beschikbaar (wachtwoorden en andere gevoelige gegevens zijn uitgesloten)
  • Ontbrekende velden worden standaard ingesteld op lege strings
  • Boolean-velden worden geconverteerd naar string-representaties ("true" of "false")
• Foutafhandeling (stderr):
  • Het configureren van stderr stelt u in staat om te beheren hoe foutmeldingen van het MCP serverproces worden afgehandeld. De standaardwaarde "inherit" betekent dat de fouten worden afgedrukt naar de stderr van het bovenliggende proces.
• Server-instructies:
  • Instructies worden automatisch in het systeembericht van de agent geïnjecteerd wanneer MCP server-tools worden gebruikt
  • Aangepaste instructies (stringwaarden) krijgen voorrang op instructies die door de server worden verstrekt
  • Meerdere MCP servers kunnen elk hun eigen instructies bijdragen aan de agent-context
  • Instructies worden alleen opgenomen wanneer de tools van de bijbehorende MCP server daadwerkelijk beschikbaar zijn voor de agent
• OAuth-authenticatie:
  • OAuth2 flow wordt ondersteund voor veilige authenticatie met MCP servers
  • Gebruikers worden gevraagd om te authenticeren via OAuth voordat de MCP server kan worden gebruikt

Referenties

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

Door de mcpServers correct te configureren in je librechat.yaml, kun je de functionaliteit van LibreChat verbeteren en aangepaste tools en services naadloos integreren.