Struktura obiektu serwerów MCP

Przykład

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

Klucz:

Podklucze

title

• Typ: Ciąg znaków (Opcjonalne)
• Opis: Niestandardowa nazwa wyświetlana serwera MCP w interfejsie użytkownika. Jeśli nie zostanie określona, używana jest nazwa klucza serwera.
• Przykład:

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

description

• Typ: Ciąg znaków (Opcjonalne)
• Opis: Opis serwera MCP, wyświetlany w interfejsie użytkownika, aby pomóc użytkownikom zrozumieć jego przeznaczenie i możliwości.
• Przykład:

  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
• Opis: Określa typ połączenia z serwerem MCP. Prawidłowe opcje to "stdio", "websocket", "streamable-http" lub "sse".
• Wartość domyślna: Określana na podstawie obecności i formatu url lub command.

command

• Typ: String
• Opis: (Dla typu stdio) Polecenie lub plik wykonywalny, który należy uruchomić, aby rozpocząć działanie serwera MCP.

args

• Typ: Tablica ciągów znaków
• Opis: (Dla typu stdio) Argumenty wiersza poleceń przekazywane do command.

url

• Typ: String
• Opis: (Dla typu websocket, streamable-http lub sse) Adres URL do połączenia z serwerem MCP. Obsługuje dynamiczne symbole zastępcze pól użytkownika ({{LIBRECHAT_USER_*}}) oraz podstawianie zmiennych środowiskowych (${ENV_VAR}).
• Uwagi:
  • Dla typu sse, URL musi zaczynać się od http:// lub https://.
  • Dla typu streamable-http, adres URL musi zaczynać się od http:// lub https://.
  • Dla typu websocket, adres URL musi zaczynać się od ws:// lub wss://.

proxy

• Typ: String (Opcjonalny, dla typów sse oraz streamable-http)
• Opis: Adres URL serwera proxy wychodzącego dla tego zdalnego serwera MCP. Wartość może odwoływać się do zmiennych środowiskowych za pomocą ${ENV_VAR}.
• Obsługiwane protokoły: http://, https://, socks:// oraz socks5://
• Uwaga dotycząca bezpieczeństwa: proxy jest kontrolowane przez administratora. Rozwiązuje ono zmienne środowiskowe, ale nie rozwiązuje symboli zastępczych kontrolowanych przez użytkownika, takich jak {{LIBRECHAT_USER_ID}} lub customUserVars.
• Przykład:

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

headers

• Typ: Obiekt (Opcjonalny, dla typów sse i streamable-http)
• Opis: Niestandardowe nagłówki przesyłane wraz z żądaniem. Obsługuje różne typy symboli zastępczych dla dynamicznego podstawiania wartości.
• Obsługa symboli zastępczych (Placeholder Support):
  • {{LIBRECHAT_USER_ID}}: Zostanie zastąpione identyfikatorem bieżącego użytkownika, co umożliwi obsługę wielu użytkowników.
  • {{LIBRECHAT_USER_*}}: Dynamiczne symbole zastępcze pól użytkownika. Zastąp * WIELKOLITEROWĄ wersją dowolnego dozwolonego pola.
  • {{LIBRECHAT_OPENID_*}}: Symbole zastępcze tokenów/sesji OpenID dla serwerów zdefiniowanych w YAML.
  • {{LIBRECHAT_GRAPH_*}}: Symbole zastępcze tokenów Microsoft Graph dla serwerów zdefiniowanych w YAML.
  • {{LIBRECHAT_BODY_*}}: Symbole zastępcze treści żądania dla serwerów zdefiniowanych w YAML, takie jak bieżące conversationId, parentMessageId lub messageId.
  • {{CUSTOM_VARIABLE_NAME}}: Zastępowane wartością podaną przez użytkownika dla zmiennej zdefiniowanej w customUserVars (np. {{MY_API_KEY}}).
  • ${ENV_VAR}: Zostanie zastąpione wartością zmiennej środowiskowej {{ENV_VAR}}.

Dostępne symbole zastępcze pól użytkownika:

Uwaga: Brakujące pola zostaną zastąpione pustymi ciągami znaków.

Symbole zastępcze {{LIBRECHAT_BODY_*}} mają zasięg ograniczony do żądania (request-scoped). LibreChat tworzy połączenie MCP dla aktywnego uruchomienia, wykorzystuje je ponownie w wywołaniach narzędzi w ramach tego uruchomienia i czyści je po zakończeniu żądania. Serwery o zasięgu żądania są wykluczone z trwałej pamięci podręcznej narzędzi, dzięki czemu nagłówki i adresy URL specyficzne dla żądania nie są ponownie wykorzystywane poza aktywnym uruchomieniem. Symbole zastępcze {{LIBRECHAT_USER_*}}, {{LIBRECHAT_OPENID_*}} oraz {{LIBRECHAT_GRAPH_*}} nadal sprawiają, że serwer ma zasięg użytkownika (user-scoped), ale transporty HTTP odświeżają rozpoznane nagłówki przed każdym wywołaniem narzędzia, nie wymuszając przy tym samodzielnie ponownego połączenia.

• Przykład:

  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: Obiekt (Opcjonalny, dla typów sse i streamable-http)

• Opis: Konfiguracja uwierzytelniania kluczem API dla serwera MCP. Zapewnia ustrukturyzowany sposób konfiguracji uwierzytelniania opartego na kluczach API.

• Podklucze:

  • source: String - Skąd pochodzi klucz API. Opcje:
    • "admin": klucz API jest skonfigurowany przez administratora (w zmiennych środowiskowych lub pliku konfiguracyjnym)
    • "user": klucz API jest dostarczany przez użytkownika za pośrednictwem interfejsu użytkownika
  • authorization_type: String – W jaki sposób klucz API jest przesyłany w żądaniach. Opcje:
    • "bearer": Wysyłane jako Authorization: Bearer <key>
    • "basic": Wysyłane jako Authorization: Basic <key>
    • "custom": Wysyłane w niestandardowym nagłówku (wymaga custom_header)
  • custom_header: String - (Wymagane, gdy authorization_type ma wartość "custom") Nazwa nagłówka używana dla klucza API

• Przykład:

  # 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: Ciąg znaków (Opcjonalne)
• Opis: Definiuje ikonę wyświetlania narzędzia, pokazywaną w oknie dialogowym wyboru narzędzi.

chatMenu

• Typ: Wartość logiczna (Opcjonalne)
• Opis: Gdy ustawiono na false, wyklucza serwer MCP z menu rozwijanego obszaru czatu (MCPSelect), co zapewnia szybki i łatwy dostęp.
• Wartość domyślna: true (Serwer MCP zostanie uwzględniony na liście rozwijanej w obszarze czatu)

serverInstructions

• Typ: Wartość logiczna (Boolean) lub ciąg znaków (String) (Opcjonalne)

• Opis: Kontroluje sposób, w jaki instrukcje serwera MCP są wstrzykiwane do kontekstu agenta. Instrukcje serwera zapewniają wskazówki dotyczące użytkowania wysokiego poziomu dla całego serwera MCP, uzupełniając opisy poszczególnych narzędzi.

• Opcje:

  • undefined (domyślnie): Brak dołączonych instrukcji
  • true: Użyj instrukcji dostarczonych przez serwer (jeśli są dostępne) – idealne dla dobrze udokumentowanych serwerów z kompleksowymi wskazówkami
  • false: Jawne wyłączenie instrukcji – przydatne w celu zaoszczędzenia tokenów kontekstu lub gdy narzędzia są zrozumiałe same w sobie
  • string: Użyj własnych instrukcji (zastępują one instrukcje dostarczone przez serwer) – najlepsze rozwiązanie dla przepływów pracy specyficznych dla aplikacji lub gdy instrukcje serwera są niewystarczające

• Wartość domyślna: undefined (brak dołączonych instrukcji)

• Uwagi:

  • Instrukcje są automatycznie wstrzykiwane, gdy skonfigurowano serverInstructions, a narzędzia serwera są dostępne dla agenta.
  • Wiele serwerów może wnosić własne instrukcje do kontekstu agenta

• Przykład:

  # 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: Obiekt (Opcjonalny, tylko typ stdio)
• Opis: Zmienne środowiskowe używane podczas uruchamiania procesu.
• Obsługa symboli zastępczych (Placeholder Support):
  • {{LIBRECHAT_USER_ID}}: Zastępowane identyfikatorem bieżącego użytkownika.
  • {{LIBRECHAT_USER_*}}: Dynamiczne symbole zastępcze pól użytkownika (np. {{LIBRECHAT_USER_EMAIL}}).
  • {{CUSTOM_VARIABLE_NAME}}: Zastępowane wartością podaną przez użytkownika dla zmiennej zdefiniowanej w customUserVars (np. {{MY_API_KEY}}).
  • ${ENV_VAR}: Zastąpione wartością zmiennej środowiskowej po stronie serwera {{ENV_VAR}}.

timeout

• Typ: Liczba całkowita (Opcjonalne)
• Opis: Limit czasu w milisekundach dla żądań serwera MCP. Musi być nieujemną liczbą całkowitą.
• Wartość domyślna: 30000 (30 sekund)

initTimeout

• Typ: Liczba całkowita (Opcjonalne)
• Opis: Limit czasu w milisekundach dla inicjalizacji serwera MCP. Musi być nieujemną liczbą całkowitą.
• Wartość domyślna: 10000 (10 sekund)

requiresOAuth

• Typ: Wartość logiczna (Opcjonalne, tylko dla transportów zdalnych: sse, streamable-http, websocket)
• Opis: Czy ten serwer wymaga uwierzytelniania OAuth. Jeśli nie zostanie określone, zostanie wykryte automatycznie podczas uruchamiania serwera. Choć jest to opcjonalne, najlepiej ustawić tę wartość jawnie, jeśli wiesz, czy serwer wymaga OAuth, czy nie.
• Wartość domyślna: Wykrywana automatycznie, jeśli nie określono inaczej
• Uwagi:
  • Ma zastosowanie do transportów zdalnych (opartych na adresach URL): sse, streamable-http oraz websocket. Nie ma wpływu na serwery stdio, które nie posiadają adresu URL do uwierzytelnienia.
  • Automatyczne wykrywanie następuje podczas uruchamiania serwera, co może wydłużyć czas inicjalizacji.
  • Jawna konfiguracja poprawia wydajność uruchamiania poprzez pominięcie wykrywania.
  • Ustaw requiresOAuth: false dla serwerów chronionych wyłącznie statycznym nagłówkiem Authorization (np. kluczem API typu Bearer). Automatyczne wykrywanie sonduje serwer bez skonfigurowanych nagłówków, więc serwer odpowiadający kodem 401 z wyzwaniem WWW-Authenticate: Bearer może zostać błędnie zaklasyfikowany jako chroniony przez OAuth; ta flaga pomija to sondowanie i pozwala statycznemu nagłówkowi na normalne uwierzytelnienie połączenia.
  • Współpracuje ze zmiennymi środowiskowymi MCP OAuth (MCP_OAUTH_ON_AUTH_ERROR, MCP_OAUTH_DETECTION_TIMEOUT, MCP_OAUTH_HANDLING_TIMEOUT, MCP_OAUTH_FLOW_TTL) w celu ulepszonego zarządzania połączeniami

stderr

• Typ: Ciąg znaków (String) lub liczba całkowita (Integer) (Opcjonalne, tylko dla typu stdio)
• Opis: Sposób obsługi stderr procesu potomnego. Odpowiada to semantyce funkcji child_process.spawn w Node.js. Prawidłowe wartości tekstowe: "pipe", "ignore", "inherit". Alternatywnie można użyć nieujemnej liczby całkowitej jako deskryptora pliku.
• Wartość domyślna: "inherit" (komunikaty do stderr będą wypisywane do stderr procesu nadrzędnego).

customUserVars

• Typ: Obiekt (Opcjonalne)
• Opis: Definiuje zmienne niestandardowe, które użytkownicy mogą ustawić dla tego serwera MCP. Pozwala to administratorom na określenie zmiennych (np. kluczy API, adresów URL), które każdy użytkownik musi skonfigurować indywidualnie. Te wartości dostarczone przez użytkownika mogą być następnie użyte w konfiguracji headers lub env. Serwery z customUserVars są automatycznie wykluczane z połączeń na poziomie aplikacji, co zapewnia, że poświadczenia dla poszczególnych użytkowników są zawsze rozwiązywane w czasie wykonywania.
• Struktura:
  • Obiekt customUserVars zawiera klucze, gdzie każdy klucz reprezentuje nazwę zmiennej (np. MY_API_KEY). Ta nazwa będzie używana w symbolach zastępczych, takich jak {{MY_API_KEY}}.
  • Każda nazwa zmiennej jest obiektem z następującymi podkluczami:
    • title: String (Wymagane) - Przyjazny dla użytkownika tytuł zmiennej, wyświetlany w interfejsie konfiguracyjnym.
    • 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 (Opcjonalne) – Określa, czy wartość jest traktowana jako sekret i maskowana w interfejsie użytkownika. Domyślnie przyjmuje zachowanie maskowania/sekretu, jeśli zostanie pominięte; ustaw na false dla pól niebędących sekretami, takich jak identyfikatory projektów (project IDs) lub podstawowe adresy URL (base URLs).
• Użycie w headers i env:
  • Po zdefiniowaniu w customUserVars, zmienne te mogą być przywoływane w sekcjach headers (dla typów sse i streamable-http) lub env (dla typu stdio) przy użyciu składni {{VARIABLE_NAME}}.
  • Użytkownicy podają te wartości za pośrednictwem interfejsu użytkownika. Do tych ustawień można uzyskać dostęp na dwa sposoby:
    • Z poziomu pola wprowadzania czatu asystenta: Podczas wybierania narzędzi MCP dla asystenta, obok konfigurowalnych serwerów MCP na liście rozwijanej wyboru narzędzi pojawi się ikona ustawień. Kliknięcie tej ikony otwiera okno dialogowe umożliwiające zarządzanie poświadczeniami dla danego serwera.
    • Z poziomu panelu ustawień: Dedykowana sekcja "MCP Settings" w prawym panelu zawiera listę wszystkich serwerów MCP z możliwością definiowania zmiennych niestandardowych. Użytkownicy mogą kliknąć serwer, aby otworzyć okno dialogowe konfiguracji w celu ustawienia lub aktualizacji danych uwierzytelniających dla tego konkretnego serwera MCP.
  • Te wartości dostarczone przez użytkownika są przechowywane w bezpieczny sposób, przypisane do konkretnego użytkownika oraz określonego serwera MCP i są podstawiane w czasie wykonywania (runtime).
• Przykład:

  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

  Użycie w 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

• Typ: Obiekt (Opcjonalny, tylko dla typów sse oraz streamable-http)
• Opis: Konfiguruje wymianę tokenów OAuth 2.0 On-Behalf-Of dla serwera MCP. LibreChat wymienia token dostępu OpenID zalogowanego użytkownika na delegowany token podrzędny z określonymi zakresami (scopes), a następnie przekazuje ten token do serwera MCP w nagłówku Authorization: Bearer ....
• Wymagane podklucze:
  • scopes: String - Niepuste zakresy (scopes) wymagane do wymiany tokenów podrzędnych.
• Weryfikacja:
  • obo jest ważne tylko dla serwerów MCP typu sse oraz streamable-http.
  • obo jest odrzucane dla serwerów stdio oraz websocket.
  • Użytkownicy potrzebują uprawnienia roli MCP_SERVERS.CONFIGURE_OBO, aby skonfigurować to pole. Zainicjuj je za pomocą interface.mcpServers.configureObo lub zarządzaj nim z poziomu panelu administratora.
• Wymagania wstępne:
  • Uwierzytelnianie OpenID musi być skonfigurowane przy użyciu tokenów dostępu wielokrotnego użytku.
  • Twój dostawca tożsamości oraz aplikacja podrzędna muszą zezwalać na żądany zakres delegowany.
• Przykład:

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

Zobacz OpenID Connect Token Reuse oraz SharePoint Integration, aby uzyskać informacje na temat powiązanego ponownego wykorzystania tokenów i konfiguracji tokenów delegowanych.

oauth

• Typ: Obiekt (Opcjonalne)
• Opis: Konfiguracja OAuth2 do uwierzytelniania z serwerem MCP. Po skonfigurowaniu użytkownicy będą proszeni o uwierzytelnienie poprzez przepływ OAuth, zanim serwer MCP będzie mógł zostać użyty. Jeśli nie podano client id oraz client secret, użyta zostanie dynamiczna rejestracja klienta (DCR).
• Wymagane podklucze:
  • authorization_url: String - Adres URL punktu końcowego autoryzacji OAuth
  • token_url: String – Adres URL punktu końcowego tokena OAuth
  • client_id: String - Identyfikator klienta OAuth
  • client_secret: String - Klucz tajny klienta OAuth
  • redirect_uri: String - URI przekierowania OAuth (np. http://localhost:3080/api/mcp/${serverName}/oauth/callback)
  • scope: String - Zakresy OAuth (oddzielone spacjami)
• Opcjonalne podklucze:
  • grant_types_supported: Tablica ciągów znaków - Obsługiwane typy grantów (domyślnie ["authorization_code", "refresh_token"])
  • token_endpoint_auth_methods_supported: Tablica ciągów znaków - Obsługiwane metody uwierzytelniania punktu końcowego tokena (domyślnie ["client_secret_basic", "client_secret_post"])
  • token_exchange_method: String - Metoda żądania wymiany tokena. Użyj default_post dla dostawców, którzy oczekują danych uwierzytelniających klienta OAuth w treści POST.
  • response_types_supported: Tablica ciągów znaków - Obsługiwane typy odpowiedzi (domyślnie ["code"])
  • code_challenge_methods_supported: Tablica ciągów znaków - Obsługiwane metody wyzwania kodu PKCE (domyślnie ["S256", "plain"])
  • skip_code_challenge_check: Boolean – Pomiń sprawdzanie, czy dostawca OAuth reklamuje wsparcie dla PKCE. Przydatne w przypadku dostawców takich jak AWS Cognito, którzy obsługują S256, ale nie reklamują tego w swoich metadanych. (domyślnie false)
• Zmienne środowiskowe: Pola URL OAuth zdefiniowane w YAML, w tym authorization_url, token_url, redirect_uri oraz revocation_endpoint, mogą korzystać z odwołań ${ENV_VAR}. LibreChat rozpoznaje wartość środowiskową przed walidacją adresu URL. Adresy URL punktów końcowych OAuth zarządzane przez użytkownika, przesyłane za pośrednictwem interfejsu użytkownika, muszą być dosłownymi adresami URL i odrzucać symbole zastępcze ${ENV_VAR}.
• Przykład:

  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: Obiekt (Opcjonalne)
• Opis: Nagłówki używane specjalnie dla żądań przepływu OAuth. Nagłówki te są wykorzystywane podczas uwierzytelniania OAuth, takiego jak dynamiczna rejestracja klienta i wymiana tokenów, i nie są wysyłane podczas zwykłej komunikacji z serwerem MCP.
• Typowe przypadki użycia:
  • Dodawanie uwierzytelniania do endpointów dynamicznej rejestracji klienta (dynamic client registration), takich jak Authorization: Bearer ${DCR_API_KEY}
  • Uwzględnienie niestandardowych nagłówków specyficznych dla dostawcy, wymaganych w przepływach OAuth
  • Ustawianie nagłówków wymaganych przez punkty końcowe tokenów OAuth
• Kluczowe różnice względem headers:
  • headers: Wysyłane wraz ze zwykłymi żądaniami serwera MCP po zakończeniu uwierzytelniania
  • oauth_headers: Wysyłane tylko podczas przepływów uwierzytelniania OAuth
• Przykład:

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

startup

• Typ: Wartość logiczna (Opcjonalne)
• Opis: Gdy ustawione na false, ten serwer MCP nie będzie łączony podczas uruchamiania aplikacji. Jest to przydatne w przypadku serwerów, które wymagają danych wejściowych lub konfiguracji użytkownika przed połączeniem, lub w sytuacjach, gdy chcesz kontrolować moment inicjalizacji serwera.
• Wartość domyślna: true
• Przykład:

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

Uwagi

• Wnioskowanie o typach:
  • Jeśli type zostanie pominięte:
    • Jeśli url jest określony i zaczyna się od http:// lub https://, type domyślnie przyjmuje wartość sse.
    • Jeśli url jest określony i zaczyna się od ws:// lub wss://, type domyślnie przyjmuje wartość websocket.
    • Jeśli określono command, type domyślnie przyjmuje wartość stdio.
• Typy połączeń:
  • stdio: Uruchamia serwer MCP jako proces potomny i komunikuje się za pomocą standardowego wejścia/wyjścia.
  • websocket: Łączy się z zewnętrznym serwerem MCP przez WebSocket.
  • sse: Łączy się z zewnętrznym serwerem MCP za pośrednictwem Server-Sent Events (SSE).
  • streamable-http: Łączy się z zewnętrznym serwerem MCP przez HTTP z obsługą przesyłania strumieniowego odpowiedzi.
• Adresy wewnętrzne/lokalne:
  • Ważne: Serwery MCP korzystające z wewnętrznych adresów IP (np. 172.24.1.165, 192.168.1.100) lub domen lokalnych (np. mcp-server, host.docker.internal) muszą zostać jawnie dozwolone. Użyj mcpSettings.allowedAddresses dla konkretnych usług typu prywatny host:port, gdy chcesz, aby publiczne miejsca docelowe pozostały osiągalne, lub mcpSettings.allowedDomains, gdy chcesz zastosować ścisłą białą listę.
  • Zobacz MCP Settings, aby uzyskać szczegółowe informacje na temat konfiguracji.

Przykłady

Konfiguracja z adresami wewnętrznymi

W przypadku korzystania z wewnętrznych/lokalnych serwerów MCP, gdy nie jest wymagana ścisła biała lista domen, skonfiguruj mcpSettings.allowedAddresses z dokładnym hostem i portem:

# 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

Serwer 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

Serwer MCP sse

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

Serwer MCP websocket

myWebSocketServer:
  url: ws://localhost:8080

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

Serwer MCP z dynamicznymi polami użytkownika

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

Serwer MCP z poświadczeniami dla użytkownika przez 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

UWAGA Zobacz MCP Server Initialization, aby uzyskać więcej informacji na temat inicjalizacji serwera opartej na interfejsie użytkownika.

Serwer MCP z własną ikoną

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

Serwer MCP z uwierzytelnianiem 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'

Serwer MCP z instrukcjami serwera

# 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

Serwer MCP z włączonym OAuth (starsza wersja 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

Powiązane zmienne środowiskowe (opcjonalne):

# 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

Importowanie konfiguracji serwera MCP

Konfiguracje mcpServers pozwalają LibreChat na dynamiczną interakcję z różnymi serwerami MCP, które mogą wykonywać wyspecjalizowane zadania lub zapewniać określone funkcjonalności wewnątrz aplikacji. To modularne podejście ułatwia rozszerzanie możliwości aplikacji poprzez proste dodawanie lub modyfikowanie konfiguracji serwerów.

Dodatkowe informacje

• Domyślne zachowanie:
  • Inicjalizacja następuje podczas uruchamiania, a aplikacja musi zostać zrestartowana, aby zmiany weszły w życie.
  • Jeśli określono zarówno url, jak i command, type musi być jawnie zdefiniowany, aby uniknąć niejednoznaczności.
• Obsługa wielu użytkowników:
  • MCPManager obsługuje teraz oddzielne połączenia na poziomie użytkownika i na poziomie aplikacji, co umożliwia właściwe zarządzanie połączeniami dla każdego użytkownika.
  • Połączenia użytkowników są śledzone i zarządzane oddzielnie, z odpowiednim ustanawianiem i czyszczeniem.
  • Używaj dynamicznych symboli zastępczych pól użytkownika w nagłówkach, adresach URL i zmiennych środowiskowych:
    • {{LIBRECHAT_USER_ID}} - Unikalny identyfikator użytkownika
    • {{LIBRECHAT_USER_EMAIL}} - Adres e-mail użytkownika
    • {{LIBRECHAT_USER_USERNAME}} - Nazwa użytkownika
    • {{LIBRECHAT_USER_ROLE}} - Rola użytkownika (np. "user", "admin")
    • I wiele innych pól (pełną listę znajdziesz w sekcji headers)
• Zarządzanie bezczynnością użytkownika:
  • Połączenia użytkowników są monitorowane pod kątem aktywności i zostaną rozłączone po 15 minutach bezczynności.
• Zmienne środowiskowe:
  • W env (dla typu stdio): Przydatne do konfigurowania określonych środowisk uruchomieniowych lub konfiguracji wymaganych przez proces serwera MCP.
  • W headers (dla typów sse oraz streamable-http): Użyj składni ${ENV_VAR}, aby odwołać się do zmiennych środowiskowych w wartościach nagłówków.
• Dynamiczne pola użytkownika:
  • Symbole zastępcze pól użytkownika są zastępowane w czasie wykonywania informacjami uwierzytelnionego użytkownika
  • Dostępne są tylko pola niebędące danymi wrażliwymi (hasła i inne dane wrażliwe są wykluczone)
  • Brakujące pola są domyślnie ustawiane jako puste ciągi znaków
  • Pola typu boolean są konwertowane na reprezentacje tekstowe ("true" lub "false")
• Obsługa błędów (stderr):
  • Konfiguracja stderr pozwala zarządzać sposobem obsługi komunikatów o błędach z procesu serwera MCP. Domyślna wartość "inherit" oznacza, że błędy będą wypisywane do stderr procesu nadrzędnego.
• Instrukcje serwera:
  • Instrukcje są automatycznie wstrzykiwane do komunikatu systemowego agenta, gdy używane są narzędzia serwera MCP.
  • Własne instrukcje (wartości typu string) mają pierwszeństwo przed instrukcjami dostarczonymi przez serwer
  • Wiele serwerów MCP może wnosić własne instrukcje do kontekstu agenta
  • Instrukcje są dołączane tylko wtedy, gdy narzędzia odpowiedniego serwera MCP są faktycznie dostępne dla agenta
• Uwierzytelnianie OAuth:
  • Przepływ OAuth2 jest obsługiwany w celu zapewnienia bezpiecznego uwierzytelniania z serwerami MCP
  • Użytkownicy zostaną poproszeni o uwierzytelnienie przez OAuth, zanim będzie można użyć serwera MCP.

Referencje

• Dokumentacja Model Context Protocol (MCP)
• Specyfikacja transportów MCP
• Node.js child_process.spawn

Poprawnie konfigurując mcpServers w pliku librechat.yaml, możesz zwiększyć funkcjonalność LibreChat i bezproblemowo zintegrować niestandardowe narzędzia oraz usługi.