Comment configurer les serveurs MCP dans LibreChat et connecter des outils externes

Si vous vous êtes déjà demandé comment faire en sorte que l'intelligence artificielle cesse de se contenter de générer du texte et soit capable de interroger des fichiers, utiliser des services externes ou exécuter des outilsLibreChat propose une solution utilisant le protocole MCP (Model Context Protocol).

El Protocole de contexte de modèle, connu sous le nom de MCPIl s'agit d'une norme ouverte qui établit une méthode commune pour connecter les modèles de langage aux sources de données et aux outils. Elle est souvent comparée à l'USB-C car elle évite de devoir développer une intégration complètement différente pour chaque application, modèle ou service.

Grâce à ce protocole, LibreChat peut se connecter avec Systèmes de fichiers, bases de données, navigateurs, dépôts de code, outils d'entreprise et APILe modèle n'obtient pas un accès illimité simplement en activant MCP : il ne peut utiliser que les fonctions exposées par chaque serveur et autorisées par l'utilisateur ou l'administrateur.

Avant d'installer un serveur, il est conseillé de vérifier son origine. Un serveur MCP peut recevoir des informations issues de conversations et exécuter des actions en fonction des autorisations qui lui ont été accordées. C'est pourquoi, Vous ne devez pas installer de serveurs inconnus ni leur fournir d'informations d'identification sensibles. sans vérifier au préalable leur code, leur documentation et leurs autorisations.

Ce dont vous avez besoin pour utiliser les serveurs MCP dans LibreChat

Pour commencer, vous devez avoir un Mise à jour de l'installation de LibreChat et l'accès à ses paramètres. Selon la méthode choisie, vous aurez également besoin de l'autorisation de modifier le fichier. librechat.yaml ou l'autorisation de créer des serveurs à partir du panneau MCP de l'interface.

Les exigences spécifiques dépendent du serveur que vous souhaitez utiliser :

• Node.js ou npx, lorsque le serveur est distribué sous forme de package JavaScript exécuté à l'aide de stdio.
• Python et ses dépendances, si le serveur est développé dans ce langage.
• Une URL accessible, lors de la gestion d'un serveur MCP distant.
• Une clé API ou une autorisation OAuth, si l'outil se connecte à un service protégé.
• Accès réseau depuis le conteneur, lorsque LibreChat est exécuté à l'aide de Docker.

Vous devez également utiliser un modèle qui prend en charge les appels d'outils. Même si le serveur est correctement connecté, Un modèle sans prise en charge des outils peut ne pas savoir comment invoquer ses fonctions ou produire des résultats peu fiables.

Comment ajouter des serveurs MCP à LibreChat

LibreChat vous permet de configurer des serveurs MCP à l'aide de deux procédures principales: depuis l'interface graphique ou en modifiant manuellement le fichier librechat.yaml.

L'interface est la méthode la plus pratique pour la plupart des utilisateurs. Depuis le panneau MCP situé dans la barre latérale droite, vous pouvez consulter les serveurs existants et utiliser le bouton correspondant pour en ajouter un nouveau. Cette procédure vous permet de saisir le nom, le protocole de transport, l'URL et les identifiants. sans modifier les fichiers ni redémarrer LibreChat.

La disponibilité de cette option peut dépendre des autorisations configurées par l'administrateur. LibreChat permet de contrôler séparément si un utilisateur peut utiliser, créer, partager ou publier des serveurs MCP.

La configuration utilisant librechat.yaml Il offre un contrôle accru et s'avère particulièrement utile pour les administrateurs, les déploiements reproductibles ou les serveurs partagés. Dans ce cas, tout nouveau serveur ou toute modification apportée au fichier nécessite Redémarrez LibreChat pour initialiser la connexion..

Une configuration simple utilisant stdio pourrait ressembler à ceci :

mcpServers:
  filesystem:
    type: stdio
    command: npx
    args:
      - -y
      - "@modelcontextprotocol/server-filesystem"
      - "/ruta/a/documentos"

Le répertoire spécifié sera accessible au serveur. Par conséquent, vous devez limiter l'accès à un emplacement précis et éviter d'accorder l'accès à... l'ensemble du système de fichiers sauf si c'est absolument nécessaire.

Vous pouvez également rechercher des serveurs dans des catalogues comme Smithery. Ces plateformes facilitent la recherche de projets disponibles et la génération de configurations compatibles. Cependant, leur présence dans un catalogue ne garantit pas la sécurité d'un serveurVérifiez toujours qui en assure la maintenance, quelles autorisations il requiert et quelles commandes il exécutera.

Comment utiliser les outils MCP dans une conversation

Une fois la connexion établie, LibreChat vous permet d'utiliser directement les serveurs MCP dans une conversation. Vous devez d'abord en sélectionner un. modèle compatible avec les outilsSous la zone de saisie du message, le sélecteur des serveurs disponibles apparaîtra.

L'activation d'un serveur met ses outils à la disposition du modèle pendant la conversation. Vous pouvez sélectionner plusieurs serveurs simultanément, mais il est préférable d'éviter d'ajouter des fonctionnalités inutiles. Un nombre excessif d'outils peut alourdir le contexte et rendre difficile le choix correct par le modèle..

L'administrateur peut empêcher un serveur d'apparaître dans ce menu en ajoutant l'option :

chatMenu: false

Dans ce cas, le serveur restera accessible aux agents, mais il n'apparaîtra pas comme un outil sélectionnable dans les conversations classiques.

Vous devriez également examiner chaque opération avant de l'approuver, surtout lorsqu'un outil peut supprimer des fichiers, modifier des bases de données, envoyer des informations ou effectuer des actions irréversibles.

Comment ajouter des outils MCP à un agent

Les serveurs MCP peuvent également être utilisés avec Agents LibreChatDepuis l'Agent Builder, vous pouvez ouvrir la section outils, sélectionner un serveur et décider quelles fonctions seront disponibles.

Ce contrôle individuel est particulièrement utile lorsqu'un serveur expose de nombreux outils. Par exemple, vous pouvez autoriser un agent à interroger une base de données, mais empêcher les autres de le faire. modifier ou supprimer des enregistrements.

LibreChat prend également en charge le chargement différé des outils. Lorsqu'une fonctionnalité est marquée comme différée, elle n'occupe pas d'espace dans le contexte du modèle initial. L'agent utilise alors un système de recherche pour la localiser en cas de besoin. Cette option permet de réduire la consommation de contexte lors de la connexion à des serveurs offrant des dizaines de fonctions.

La recommandation générale est d'appliquer le principe du moindre privilège : chaque agent ne devrait avoir que des privilèges limités. les outils essentiels pour accomplir leur fonction.

Types de transport disponibles pour MCP

LibreChat prend actuellement en charge les transports suivants stdio, HTTP en flux continu, SSE et WebSocketLe choix dépend de l'emplacement où le serveur est exécuté et de la manière dont il doit communiquer avec LibreChat.

Transport stdio Il lance un processus local et communique avec lui via les entrées et sorties standard. Ceci est courant sur les serveurs fonctionnant sous npxPython ou d'autres commandes locales. C'est pratique pour les installations personnelles, mais cela peut se compliquer dans Docker ou les environnements distribués.

Pour les nouveaux serveurs distants, Streamable HTTP est généralement l'alternative la plus recommandée.Il fonctionne via HTTP et est particulièrement adapté aux services hébergés, aux déploiements multi-utilisateurs et aux systèmes nécessitant une évolutivité.

Une configuration de base à distance pourrait être :

mcpServers:
  herramientas-remotas:
    type: streamable-http
    url: "https://ejemplo.com/mcp"
    timeout: 60000
    initTimeout: 10000

Transport SSE Il reste pris en charge et peut s'avérer nécessaire pour les serveurs plus anciens utilisant les événements envoyés par le serveur (SSE). WebSocket est également disponible pour les services qui maintiennent une communication persistante via des adresses. ws:// o wss://.

Si le champ est omis typeLibreChat peut déduire le transport à partir de la présence de command ou le format d'URL. Malgré cela, Le fait de l'indiquer explicitement facilite la lecture et le diagnostic. de la configuration.

Paramètres importants du fichier librechat.yaml

Les paramètres nécessaires varient selon le transport utilisé. Sur les serveurs stdio, les principaux champs sont : command y argsLe premier indique le programme à exécuter, et le second contient les arguments soumis au processus.

Il peut également être utilisé env pour fournir les variables d'environnement :

mcpServers:
  servidor-local:
    type: stdio
    command: npx
    args:
      - -y
      - "paquete-del-servidor"
    env:
      NODE_ENV: "production"

Dans le transport à distance, le paramètre essentiel est urlOn peut également les ajouter En-têtes HTTP, proxy sortant, authentification et variables dynamiques.

Voici d'autres paramètres importants :

• timeout: Durée maximale autorisée pour effectuer une opération.
• initTimeout: Temps disponible pour initialiser le serveur.
• startup: Cela vous permet d'empêcher le serveur de se connecter au démarrage de LibreChat.
• chatMenu: Vérifiez si elle apparaît dans le sélecteur de zone de chat.
• requiresOAuth: Indique si le serveur distant requiert une authentification OAuth.
• headers: Il permet d'envoyer des en-têtes personnalisés dans les connexions distantes.

Il est déconseillé de stocker les clés directement dans un fichier destiné à être téléchargé sur GitHub. Pour les secrets partagés par l'ensemble de l'installation, il est plus sûr d'utiliser un système de gestion de clés. variables d'environnement telles que ${NOMBRE_VARIABLE}.

Comment connecter des serveurs MCP lors de l'utilisation de Docker ?

Lorsque LibreChat s'exécute dans un conteneur Docker, les commandes et les adresses sont interprétées. depuis le conteneur et non depuis le système hôteCette différence explique bon nombre des erreurs de connexion.

Si vous configurez un serveur stdio qui utilise Node.js, Python ou une application spécifique, ces dépendances doivent être disponibles dans le conteneur exécutant LibreChat. Elles doivent être installées uniquement sur le système hôte Windows ou Linux. Cela ne signifie pas que le conteneur peut les utiliser..

Vous devez également faire attention à localhostDans un conteneur, cette adresse fait référence au conteneur lui-même. Si le serveur MCP s'exécute sur la machine hôte, vous devrez peut-être utiliser une adresse comme :

http://host.docker.internal:3001/mcp

Le chemin exact dépend du système d'exploitation et de la configuration Docker. Une autre option consiste à exécuter le serveur MCP dans son propre conteneur et à connecter les deux services via le même réseau Docker Compose.

Avant de modifier LibreChat, vérifiez que le point de terminaison répond bien depuis le conteneur. Cela vous permettra de distinguer un problème de protocole d'un problème lié au protocole lui-même. une défaillance de réseau, de DNS, de port ou de dépendance.

Authentification OAuth pour les serveurs MCP

LibreChat prend en charge OAuth 2.0 pour l'authentification individuelle des utilisateurs Lors de l'accès à des serveurs MCP distants, lorsqu'il détecte qu'un serveur requiert une authentification, il affiche l'option permettant de lancer la procédure depuis le navigateur.

L'URL de retour suit ce format :

https://tu-dominio.com/api/mcp/nombre-del-servidor/oauth/callback

Le nom doit correspondre exactement à la clé utilisée dans mcpServers ou avec le nom attribué au serveur depuis l'interface. Dans une installation Docker locale, l'adresse de base typique pourrait être :

http://localhost:3080/api/mcp/nombre-del-servidor/oauth/callback

Cette URL doit être enregistrée exactement auprès du fournisseur OAuth. Un protocole incorrect, un port différent ou une variation dans le nom entraîneront généralement des problèmes. erreurs de redirection ou rappel invalide.

Les jetons OAuth sont stockés par utilisateur, de sorte que chaque personne accède au service externe avec leur propre compte et leurs propres autorisationsCeci est particulièrement important dans les installations partagées.

Comment utiliser des mots de passe différents pour chaque utilisateur

Tous les services ne proposent pas OAuth. Pour les serveurs qui utilisent des clés API ou d'autres identifiants, LibreChat fournit customUserVars.

Cette fonction vous permet de demander une valeur à chaque utilisateur, puis de l'utiliser dans un en-tête ou une variable d'environnement. Par exemple :

mcpServers:
  servicio-remoto:
    type: streamable-http
    url: "https://api.ejemplo.com/mcp"
    headers:
      Authorization: "Bearer {{MCP_API_KEY}}"
    customUserVars:
      MCP_API_KEY:
        title: "Clave de API"
        description: "Introduce tu clave personal"

Chaque utilisateur saisit ses identifiants dans les paramètres de LibreChat. Ainsi, l'administrateur n'a pas besoin de les stocker. une seule clé partagée pour tous les membres.

Ces variables peuvent également être utilisées sur les serveurs stdio via la section envToutefois, si vous constatez que le serveur reçoit littéralement le marqueur au lieu de la valeur attendue, vous devriez vérifier que la version installée de LibreChat est récente.

signets dynamiques et autorisations utilisateur

LibreChat vous permet d'envoyer au serveur des informations dynamiques concernant la personne effectuant la requête. Parmi les marqueurs disponibles figurent des champs tels que :

{{LIBRECHAT_USER_ID}}
{{LIBRECHAT_USER_EMAIL}}
{{LIBRECHAT_USER_ROLE}}

Ces valeurs peuvent être intégrées à l'URL ou aux en-têtes pris en charge afin que le serveur sache quel utilisateur exécute chaque outil.

Voici un exemple d'en-têtes dynamiques :

headers:
  X-User-ID: "{{LIBRECHAT_USER_ID}}"
  X-User-Email: "{{LIBRECHAT_USER_EMAIL}}"
  X-User-Role: "{{LIBRECHAT_USER_ROLE}}"

Ces données peuvent servir à appliquer les autorisations, à consigner les transactions ou à allouer des ressources. Toutefois, le serveur MCP doit valider ces informations et ne pas se fier aveuglément à un en-tête pour protéger les opérations sensibles.

LibreChat dispose également de contrôles permettant de déterminer qui peut utiliser, créer, partager ou modifier chaque serveur MCPAu sein des organisations, il est conseillé de combiner ces autorisations avec les restrictions spécifiques au service externe.

Comment vérifier l'état d'un serveur MCP

Le panneau MCP affiche indicateurs d'état dynamiques Pour faciliter le diagnostic, une roue dentée verte indique une connexion active ; une clé orange indique qu’une authentification est requise ; et un triangle rouge signale une erreur.

Si un serveur cesse de répondre, vous pouvez essayer Redémarrez votre connexion depuis l'interface.Cela évite de redémarrer l'application entière alors que le problème n'affecte qu'un seul serveur.

Si le problème persiste, vérifiez :

• Journaux des serveurs LibreChat et MCP.
• Que la commande spécifiée existe dans l'environnement d'exécution.
• Assurez-vous que l'URL et le port sont accessibles depuis LibreChat.
• Que la clé API ou le jeton reste valide.
• Assurez-vous que le serveur utilise un protocole de transport compatible.
• Que le modèle sélectionné prenne en charge les appels d'outils.
• Que l'utilisateur dispose de l'autorisation d'utiliser le serveur.

Le voyant vert confirme que la connexion est établie, mais ne garantit pas le bon fonctionnement de tous les outils. Une opération spécifique peut encore échouer. Autorisations insuffisantes, paramètres incorrects ou erreurs de service externe.

Comment corriger les erreurs de délai d'attente ?

Les serveurs traitant des requêtes complexes peuvent nécessiter un délai de réponse plus long qu'une conversation instantanée standard. Dans ce cas, vous pouvez augmenter le temps de réponse. timeout pour les opérations et initTimeout pour le début.

Par exemple:

timeout: 120000
initTimeout: 30000

Les valeurs sont exprimées en millisecondes. Il est déconseillé de les augmenter sans discernement, car un délai trop long peut entraîner un retard considérable dans la reprise d'une opération bloquée.

Si vous utilisez Nginx, Traefik, Cloudflare ou un autre proxy, vérifiez également ses limites. Bien que LibreChat attende deux minutes, le proxy peut fermer la connexion plus tôt et provoquer une réponse incomplète ou une erreur réseau.

Lors de l'utilisation de Streamable HTTP ou SSE, vérifiez également que le proxy permet le maintien de la connexion pendant la durée nécessaire et ne met pas en mémoire tampon de manière incorrecte les réponses transmises.

Quels serveurs MCP valent la peine d'être installés ?

Le choix dépend de la tâche à accomplir. Un serveur de fichiers peut être utile pour consulter la documentation locale, tandis qu'un serveur connecté à une base de données permet… Obtenez des informations mises à jour sans copier les journaux dans le chat.

Parmi les autres utilisations courantes, on peut citer :

• Consulter les référentiels et gérer les problèmes de développement.
• Effectuer des recherches Web ou contrôler un navigateur.
• Accédez à des bases de données telles que PostgreSQL ou ClickHouse.
• Connectez les services d'entreprise via OAuth.
• Exécuter les automatisations et les outils internes.

Il n'est pas nécessaire d'installer plusieurs serveurs dès le départ. Il est préférable de commencer par un seul, de vérifier ses permissions et les actions qu'il peut effectuer. Vous pourrez ensuite étendre progressivement l'installation et lui attribuer des tâches. des outils différents pour chaque agent.

L'intégration de MCP transforme LibreChat en bien plus qu'une simple interface de conversation avec des modèles. Grâce à des serveurs locaux ou distants, vous pouvez accéder à des informations actualisées et exécuter des fonctions externes depuis un système unique.

La configuration la plus simple consiste à ajouter un serveur depuis le panneau MCP. Pour les déploiements gérés, librechat.yaml Il offre un meilleur contrôle sur le transport, les temps d'attente, l'authentification et les variables dynamiques. Dans les deux cas, la sécurité doit être une priorité. Examinez le serveur, limitez ses autorisations et autorisez avec soin les actions sensibles..