Bot IA – Apportez votre propre serveur MCP

Documentation Gestion de site
,
1

:bookmark: Ce guide explique comment connecter des serveurs externes Model Context Protocol (MCP) aux agents Discourse AI, permettant à n’importe quel fournisseur d’outils compatible MCP d’être utilisé directement dans le bot IA.

:person_raising_hand: Niveau utilisateur requis : Administrateur

Qu’est-ce que “Bring Your Own MCP” ?

Model Context Protocol est une norme ouverte (initialement proposée par Anthropic) qui permet aux agents IA de communiquer avec des serveurs d’outils externes via une interface standard HTTP/JSON-RPC. Un serveur MCP expose un menu d’« outils » — des fonctions avec des entrées typées — qu’un LLM peut appeler pour accomplir des tâches.

Discourse AI agit désormais en tant que client MCP. Vous enregistrez n’importe quel serveur MCP HTTPS dans le panneau d’administration, Discourse découvre ses outils disponibles, et ces outils deviennent des citoyens de première classe dans tout agent IA que vous choisissez. Aucune écriture de JavaScript n’est requise ; les outils sont définis par le serveur distant.

Cela diffère des outils de scripts personnalisés qui nécessitent l’écriture de JavaScript s’exécutant dans Discourse. Avec MCP, vous apportez un serveur externe déjà en cours d’exécution.

Résumé

  • Enregistrer un serveur MCP (URL + authentification optionnelle)
  • Discourse découvre et met en cache automatiquement les outils du serveur
  • Assigner le serveur à un ou plusieurs agents IA
  • Limiter optionnellement les outils que chaque agent peut utiliser
  • Les outils sont appelés par le LLM à l’exécution, acheminés via Discourse vers le serveur externe

Enregistrement d’un serveur MCP

Accédez à :

Admin → Plugins → Discourse AI → Outils → Onglet Serveurs MCP → Nouveau serveur MCP

Remplissez les champs suivants :

Champ Description
Nom Un libellé lisible par un humain (affiché dans l’éditeur d’agent et les journaux)
Description À quoi sert ce serveur (référence administrateur)
URL Le point de terminaison HTTPS du serveur MCP — doit être une URL HTTPS publique, aucune adresse IP privée
Authentification L’une des options suivantes : Aucune authentification, Identifiants d’en-tête, ou OAuth
Délai d’attente (secondes) Durée d’attente de Discourse par requête — défaut 30, maximum 300
Activé Basculer pour désactiver temporairement le serveur sans le supprimer

:warning: Les URLs doivent utiliser HTTPS. localhost et les adresses privées RFC-1918 sont bloquées (la protection SSRF est appliquée côté serveur).

Options d’authentification

Aucune authentification

Le serveur est accessible publiquement. Aucun identifiant n’est envoyé.

Identifiants d’en-tête

Une valeur secrète est injectée en tant qu’en-tête HTTP sur chaque requête.

  1. Créez d’abord un Identifiant dans Admin → IA → Identifiants
  2. Sélectionnez-le comme Identifiant dans le formulaire du serveur MCP
  3. Définissez le nom de l’En-tête d’authentification (par défaut : Authorization)
  4. Définissez le préfixe de Schéma d’authentification optionnel (par défaut : Bearer)

L’en-tête de requête envoyé au serveur MCP sera :

Authorization: Bearer <valeur-secrete>

Vous pouvez modifier à la fois le nom de l’en-tête et le schéma pour correspondre à tout style d’authentification requis par votre serveur (par exemple, X-Api-Key: <valeur> en laissant le schéma vide).

OAuth

Discourse implémente un flux complet OAuth 2.0 + PKCE en tant que client MCP. Cela prend en charge les serveurs MCP qui protègent leurs outils derrière OAuth.

Étapes de configuration :

  1. Définissez Authentification sur OAuth
  2. Choisissez Enregistrement du client :
    • Document de métadonnées du client (par défaut) — Discourse publie ses propres métadonnées de client OAuth à l’adresse https://votre-site.com/discourse-ai/mcp/oauth/client-metadata. Si le serveur MCP prend en charge RFC 7591 Enregistrement dynamique de client, Discourse s’enregistrera automatiquement
    • Identifiants de client manuels — saisissez votre ID client OAuth pré-enregistré et choisissez un Secret de client OAuth dans les identifiants
  3. Définissez optionnellement les Portées OAuth (séparées par des espaces)
  4. Enregistrez le serveur
  5. Cliquez sur Connecter — Discourse vous redirigera vers la page d’autorisation du fournisseur
  6. Après autorisation, vous êtes renvoyé à l’administration et le statut affiche Connecté

Options OAuth avancées (activez « Afficher les options avancées ») :

Option Objectif
Paramètres d’autorisation OAuth Objet JSON fusionné dans la demande d’autorisation (par exemple {"access_type":"offline"})
Paramètres de jeton OAuth Objet JSON fusionné dans les demandes d’échange de jetons
Exiger un jeton de rafraîchissement Échec de la connexion si le fournisseur ne renvoie pas de jeton de rafraîchissement

Discourse rafraîchit automatiquement les jetons d’accès avant leur expiration et réessaie en cas de 401 si un jeton de rafraîchissement est disponible.

Tester la connexion

Avant d’assigner un serveur à un agent, utilisez le bouton Tester la connexion dans le formulaire de l’éditeur. Cela initialise immédiatement une session MCP, appelle tools/list, et retourne :

  • La version du protocole MCP négociée
  • Le nombre d’outils découverts
  • Les noms de tous les outils

Si le test échoue, le message d’erreur du serveur (ou un indicateur de délai d’attente) est affiché en ligne.

Comment Discourse découvre les outils

Discourse suit la spécification MCP 2025-03-26. La séquence de connexion est :

Discourse → POST /  { method: "initialize", params: { protocolVersion, capabilities, clientInfo } }
Serveur   → { result: { protocolVersion, capabilities } } + En-tête Mcp-Session-Id
Discourse → POST /  { method: "notifications/initialized" }   (poignée de main de session terminée)
Discourse → POST /  { method: "tools/list", session_id: … }
Serveur   → { result: { tools: [ { name, description, inputSchema } … ] } }

Les définitions d’outils sont mises en cache pendant 1 heure par serveur. Après l’expiration du cache, un travail en arrière-plan le rafraîchit de manière transparente. La clé de cache est par site/par serveur, de sorte que les installations multi-sites sont isolées.

Vous pouvez également déclencher manuellement un rafraîchissement en cliquant sur Tester la connexion — cela récupère toujours des données en direct.

Le statut de santé du serveur (healthy / error) est mis à jour à chaque rafraîchissement du cache.

Assignation des serveurs MCP aux agents IA

Une fois un serveur enregistré, assignez-le à un agent :

  1. Allez dans Admin → Plugins → Discourse AI → Agents et modifiez ou créez un agent
  2. Faites défiler jusqu’à la section Serveurs MCP (en dessous de la section Outils réguliers)
  3. La liste affiche tous les serveurs MCP activés avec leur nombre d’outils et le coût estimé en jetons
  4. Activez un serveur — il est maintenant disponible pour cet agent

Astuce : Par défaut, tous les outils d’un serveur sont rendus disponibles pour l’agent. La chaîne de langue locale le dit bien : « Les serveurs MCP sélectionnés exposent par défaut tous leurs outils. Restreignez-les par agent pour réduire l’utilisation des jetons et garder le choix des outils focalisé. »

Sélection d’outils spécifiques par agent

Avoir des dizaines d’outils disponibles augmente le coût en jetons de chaque message (chaque définition d’outil est envoyée au modèle dans l’invite système). Pour garder les choses légères :

  1. Dans l’éditeur d’agent, à côté d’un serveur MCP assigné, cliquez sur Choisir les outils
  2. Une fenêtre modale affiche chaque outil que le serveur expose actuellement, avec sa description et la liste des paramètres
  3. Cochez uniquement les outils dont cet agent a besoin
  4. Cliquez sur Enregistrer — l’agent ne verra maintenant que le sous-ensemble sélectionné

La table de jointure ai_agent_mcp_servers stocke selected_tool_names sous forme de tableau JSONB. Un tableau vide signifie « tous les outils activés ».

Nommage des outils et résolution des conflits

Les noms d’outils MCP doivent être uniques dans la liste des outils d’un seul agent (y compris les outils intégrés et les outils de scripts personnalisés de l’agent). Discourse gère les conflits automatiquement :

  • Si deux serveurs MCP différents exposent un outil avec le même nom, Discourse les espace : nomserveur__nomoutil
  • Si un outil Discourse intégré et un outil MCP partagent un nom, l’outil MCP est également espacé
  • S’il y a encore des collisions après l’espacement, un suffixe numérique est ajouté (_2, _3, …)

Le function_name utilisé dans l’appel LLM peut donc différer du tool_name brut sur le serveur MCP. Cela est géré de manière transparente — la classe d’outil MCP stocke toujours l’original tool_name_value séparément et l’utilise lors de l’appel au serveur.

Fonctionnement des appels d’outils à l’exécution

Lorsque le LLM décide d’utiliser un outil MCP :

  1. Réutilisation de session : Discourse recherche un ID de session MCP mis en cache pour ce serveur dans le contexte actuel du bot (context.mcp_state). Les sessions sont créées par chaîne de réponse du bot et réutilisées pour les appels d’outils vers le même serveur.
  2. Initialisation si nécessaire : Si aucune session n’existe, une nouvelle poignée de main initialize + notifications/initialized est exécutée.
  3. Appel : POST / avec { method: "tools/call", params: { name: tool_name, arguments: params } }
  4. Expiration de session : Si le serveur renvoie 404 (session expirée), Discourse réinitialise automatiquement et réessaie une fois.
  5. Normalisation de la réponse : Les éléments de contenu MCP de type text sont concaténés. Les éléments non textuels sont sérialisés en JSON. structuredContent est un JSON joliment formaté.
  6. Résultat d’erreur : Si le serveur renvoie isError: true, le bot reçoit un message d’erreur plutôt qu’un résultat.

La réponse du serveur peut être un JSON brut ou un flux SSE — Discourse gère les deux.

Affichage du coût en jetons

Dans l’éditeur d’agent, chaque serveur MCP assigné affiche un nombre estimé de jetons. Cela est calculé en utilisant le tokeniseur OpenAI cl100k_base appliqué à la signature JSON complète de chaque outil (nom + description + schéma d’entrée). C’est une approximation — le coût réel dépend du tokeniseur de votre LLM.

La ventilation du coût en jetons est affichée pour vous aider à prendre des décisions éclairées sur quels serveurs et outils assigner à un agent donné.

Dépannage

Symptôme Vérifier
Test de connexion échoue avec délai d’attente Augmentez le Délai d’attente (secondes). La valeur par défaut est 30. Si le serveur est lent à s’initialiser, essayez 60–120.
Test réussi mais les outils n’apparaissent pas dans l’agent Assurez-vous que le serveur est Activé et que l’agent l’a activé dans sa section Serveurs MCP.
Statut OAuth affiche « Nécessite une attention » La dernière erreur OAuth est affichée dans le formulaire de l’éditeur. Causes courantes : jeton de rafraîchissement expiré (cliquez sur Reconnecter), le serveur a renvoyé des portées inattendues, ou l’URL de métadonnées du client n’est pas accessible depuis votre serveur.
Les noms d’outils ressemblent à myserver__sometool Normal — un autre outil (intégré ou d’un autre serveur) avait le même nom. Le LLM voit et utilise automatiquement ce nom espacé.
Santé affiche « error » après une période Le travail de rafraîchissement en arrière-plan n’a pas pu atteindre le serveur. Vérifiez /logs sur votre site et assurez-vous que le serveur MCP est accessible depuis l’hôte de Discourse.
Les outils ont cessé de fonctionner en milieu de conversation Expiration de session. Discourse réessaie automatiquement une fois par appel d’outil, mais si le serveur redémarre constamment, raccourcissez son TTL de session ou examinez les journaux côté serveur.

Pour un débogage plus approfondi, activez l’accès aux transcriptions IA via ai_bot_debugging_allowed_groups et inspectez le journal de conversation complet.

Référence technique

Détails du protocole MCP

Propriété Valeur
Version du protocole 2025-03-26
Transport HTTP POST (JSON-RPC 2.0)
Support SSE Oui (pour le streaming des réponses tools/call)
Gestion de session En-tête HTTP Mcp-Session-Id
Taille max de réponse 5 Mo
User-Agent du client Discourse AI MCP Client / <version>

Prise en charge du schéma JSON

Discourse résout les constructions JSON Schema suivantes dans les définitions inputSchema des outils avant de les transmettre au LLM :

  • $ref — résolu par rapport à $defs / definitions du schéma racine
  • allOf — fusionné (les propriétés et les tableaux requis sont fusionnés par union)
  • anyOf / oneOf — la première variante non null est utilisée

Fichiers source pertinents

Sujets connexes

:bulb: La fonctionnalité Discourse en tant que serveur MCP (discourse/discourse-mcp) est le complément de ceci : elle permet aux clients IA externes (Claude Code, Cursor, etc.) de lire et d’écrire sur votre site Discourse. Ce guide est l’inverse — il permet à vos agents Discourse AI d’appeler des serveurs MCP externes.

3 « J'aime »
Bring your own MCP!