Structure de l'objet des paramètres MCP

Aperçu

La configuration mcpSettings fournit des paramètres globaux pour la sécurité et le comportement des serveurs MCP (Model Context Protocol). Cette configuration est distincte de mcpServers et contrôle la manière dont les serveurs MCP peuvent se connecter à certains domaines et adresses IP.

Exemple

# Example MCP Settings Configuration
mcpSettings:
  # Strict whitelist mode:
  # allowedDomains:
  #   - "example.com"                    # Specific domain
  #   - "*.example.com"                  # All subdomains using wildcard
  #   - "https://api.example.com:8443"   # With protocol and port
  #   - "http://mcp-server:3000"         # Internal service, explicitly whitelisted
 
  # Default SSRF mode with private service exemptions:
  allowedAddresses:
    - "host.docker.internal:8080"        # Permit one private host on one port
    - "10.0.0.5:8000"                    # Permit one private IP on one port

Configuration

Sous-clés

Contexte de sécurité (Protection SSRF)

LibreChat inclut une protection contre les SSRF (Server-Side Request Forgery) avec le comportement suivant :

Lorsque allowedDomains n'est PAS configuré :

• Les cibles vulnérables aux SSRF sont bloquées par défaut
• Tous les autres domaines externes sont autorisés

Lorsque allowedDomains EST configuré :

• Seuls les domaines figurant sur la liste sont autorisés
• Les cibles internes/SSRF peuvent être autorisées en les ajoutant explicitement à la liste

Les cibles SSRF bloquées incluent :

• Les adresses Localhost (localhost, 127.0.0.1, ::1)
• Plages d'adresses IP privées (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
• Adresses link-local (169.254.0.0/16, inclut les IP de métadonnées cloud)
• TLD internes (.internal, .local, .localhost)
• Noms de services internes courants (redis, mongodb, postgres, api, rag_api, etc.)

Si vos serveurs MCP doivent se connecter à des services internes ou à des conteneurs Docker, ajoutez-les à la liste blanche stricte allowedDomains, ou laissez allowedDomains non défini et ajoutez le service privé exact à allowedAddresses.

Formats de modèles

Le tableau allowedDomains prend en charge plusieurs formats de modèles :

1. Correspondance exacte de domaine

   allowedDomains:
     - "example.com"

   Autorise uniquement les connexions exactement vers example.com (n'importe quel protocole/port)

2. Correspondance de sous-domaine générique

   allowedDomains:
     - "*.example.com"

   Autorise les connexions à tous les sous-domaines de example.com (par ex. api.example.com, mcp.example.com)

3. Adresse IP spécifique

   allowedDomains:
     - "192.168.1.100"
     - "172.24.1.165"

   Autorise les connexions à des adresses IP spécifiques

4. Domaines Docker locaux

   allowedDomains:
     - "mcp-server"
     - "host.docker.internal"

   Permet les connexions aux noms de conteneurs Docker ou aux domaines Docker spéciaux

5. Avec protocole et port

   allowedDomains:
     - "https://api.example.com:8443"
     - "http://internal-mcp:3000"

   Restreint les connexions à des combinaisons spécifiques de protocoles et de ports

Messages d'erreur

Si vous voyez des erreurs telles que :

  error: [MCPServersRegistry] Failed to inspect server "my-mcp": Domain "http://172.24.1.165:8000" is not allowed
  error: [MCP][my-mcp] Failed to initialize: Domain "http://172.24.1.165:8000" is not allowed

Cela indique probablement que l'hôte privé et le port du serveur MCP doivent être ajoutés à allowedAddresses, à moins que vous n'utilisiez intentionnellement allowedDomains comme liste blanche stricte :

mcpSettings:
  allowedAddresses:
    - "172.24.1.165:8000"    # Add the private host/IP and MCP port

allowedAddresses

allowedAddresses est une liste d'exemption pour le blocage d'IP privées SSRF — et non une liste blanche de domaines. C'est l'outil approprié lorsque vous souhaitez autoriser un ou deux services privés/internes spécifiques sans restreindre ce que vos serveurs MCP peuvent atteindre sur l'internet public.

Quand l'utiliser à la place de allowedDomains

allowedDomains est une liste blanche stricte : lorsqu'elle est définie, seules les entrées listées sont accessibles. L'ajout d'une IP privée pour autoriser, par exemple, un serveur MCP auto-hébergé bloque également toutes les destinations publiques (api.example.com, *.googleapis.com, etc.) que vous n'avez pas également listées.

allowedAddresses est utilisé uniquement lorsque allowedDomains n'est pas configuré. Il autorise des cibles host:port privées spécifiques tout en laissant le reste de l'internet public accessible via la politique SSRF par défaut. Configuration courante :

mcpSettings:
  allowedAddresses:
    - "host.docker.internal:8080"
    - "10.0.0.5:8000"
  # allowedDomains is intentionally not set — public destinations
  # remain reachable, only listed private host:port services are exempted.

Si allowedDomains est configuré, il fait autorité : les services privés doivent y être listés au lieu de se reposer sur allowedAddresses.

Entrées acceptables

• Noms d'hôtes avec port : host.docker.internal:8080, mcp-server:3000, localhost:3001
• Littéraux IPv4 privés avec port : 10.0.0.5:8000, 127.0.0.1:3001, 192.168.1.10:443, 169.254.169.254:80
• Littéraux IPv6 privés entre crochets avec port : [::1]:3001, [fc00::1]:8080, [fe80::1]:8080

Entrées rejetées (validées au chargement de la configuration)

• URLs / chemins / plages CIDR : http://10.0.0.5, 10.0.0.0/24, /path
• Noms d'hôtes ou adresses IP bruts : localhost, 10.0.0.5, ::1, [::1] — chaque entrée doit inclure un port
• Ports invalides : localhost:0, localhost:65536, localhost:http
• Littéraux d'IP publiques : 8.8.8.8:53, 1.1.1.1:53, [2001:4860::8888]:443 — le champ est limité à l'espace IP privé ; les IP publiques ne sont pas des cibles SSRF et une exemption d'IP publique n'a aucune utilité défensive.

Confiance du nom d'hôte

Une entrée de nom d'hôte fait confiance à toute adresse IP vers laquelle ce nom d'hôte est résolu au moment de l'exécution sur le port indiqué. Si le DNS d'un nom d'hôte listé est modifié ou détourné pour pointer vers une adresse IP privée différente, l'exemption suit ce changement. Ne listez que les noms d'hôtes dont vous contrôlez le DNS. Privilégiez les adresses IP littérales lorsque vous le pouvez.

Références

• Configuration des serveurs MCP
• Fonctionnalités MCP
• Actions allowedAddresses (concept similaire pour les Actions)