Chatbotaurus en 5 minutes

Chatbotaurus est une plateforme MGaaS (MCP Gateway as a Service) souveraine européenne, écrite en Rust : un backend Axum (forge-api) et un frontend Dioxus compilé en wasm (forge-ui). Elle réunit un agent conversationnel, une passerelle MCP et des fiches de connecteurs YAML.

Cette page montre un chemin court : lancer la pile en local, ouvrir l'application, poser une première question.

Chiffres du catalogue : 195 fiches YAML de connecteurs, mesurées le 3 octobre 2026 (connectors/*.yaml). Le nombre exact change à chaque ajout ; la source est le dossier, pas cette page.

Trois parcours de lecture

Ce livre se lit selon votre rôle. Chaque étape renvoie au chapitre qui la traite ; la page que vous lisez reste un chemin court pour lancer la pile en local.

Décideur (dirigeant, délégué à la protection des données, acheteur)

1. Cas d'usage par secteur : ce que la plateforme fait pour votre métier
2. Tarification et offres : les quatre offres et les capacités par plan
3. SLA, support et niveaux de service : disponibilité, délais de support, pénalités
4. Conformité RGPD : données personnelles, hébergement et sous-traitants dans l'UE
5. Comparatifs : ce qui distingue une passerelle hébergée dans l'UE
6. Limites et ce que la plateforme ne fait pas : le périmètre, dit sans détour

Délégué à la protection des données (répondre à une demande d'un utilisateur, documenter la sous-traitance) : Conformité RGPD, Paramètres (la page Compte porte l'export et la suppression), Journaux (chaîne d'audit) et Réponse aux incidents (notification d'une violation).

Utilisateur (responsable métier, équipe)

En production, l'application est sur app.chatbotaurus.eu (voir En production). En local, lancez d'abord la pile avec le chemin court plus bas.

1. Prise en main guidée : du compte au premier workflow
2. Tableau de bord : la première page après la connexion
3. Workflows : l'éditeur, la palette de nœuds, les exécutions
4. Chat : parler à un workflow déployé
5. Connaissances : collections de documents et recherche ancrée (l'envoi de documents depuis l'application n'est pas encore branché)
6. Questions fréquentes : les réponses courtes aux questions courantes

Pour brancher votre Odoo : Sécurité et identifiants (enregistrer les identifiants), puis Connecter Odoo à la passerelle MCP (un premier outil appelé, puis le chat).

Opérateur ou intégrateur (développeur, administrateur système)

1. Installation de Chatbotaurus : compiler et lancer la pile
2. Variables d'environnement : chaque variable lue par le code
3. Déploiement avec Podman : deux plans, unités Quadlet en production
4. Créer votre premier connecteur MCP : une fiche YAML, sans Rust
5. Routes MCP (Streamable HTTP) : le transport, les sessions, le catalogue
6. Supervision : points de santé et métriques en service

Une fois la pile en service : Sauvegarde et restauration, Gestion des conteneurs (mise à jour, dépannage) et Réponse aux incidents.

Pour appeler l'API depuis un script : Documentation Swagger (obtenir un jeton), puis Connecter Odoo à la passerelle MCP (un premier appel d'outil de bout en bout) et Gestion des erreurs (lire un code d'erreur).

Prérequis

Installez le CLI Dioxus avec :

cargo install dioxus-cli --locked

1. Récupérer le dépôt

git clone <url-du-depot>
cd <dossier-du-depot>
cp .env.example .env

Éditez .env. Les valeurs secrètes de .env.example sont des gabarits CHANGE_ME_... : l'application refuse de démarrer avec elles. Générez les vôtres, par exemple avec openssl rand -hex 64.

Variables minimales (toutes lues par le code ; la liste complète est dans Variables d'environnement) :

DATABASE_URL=postgresql://<utilisateur>:<mot-de-passe>@localhost:5432/<base>
REDIS_URL=redis://localhost:6380
JWT_SECRET=<64 octets hexadécimaux>
QDRANT_URL=http://localhost:6334
OLLAMA_BASE_URL=http://localhost:11434
SMTP_HOST=<serveur-smtp>
SMTP_USER=<compte>
SMTP_PASSWORD=<mot-de-passe-applicatif>

Pourquoi le SMTP : le second facteur (FORCE_2FA, vrai par défaut) envoie un code par courriel. Sans SMTP configuré, le démarrage est refusé.

2. Lancer l'infrastructure

Le dépôt a deux plans compose (voir Déploiement avec Podman). Pour un premier essai, le plan chatbotaurus-vps1 suffit (PostgreSQL, Valkey, Qdrant, Ollama, Authentik, OpenBao, voix, observabilité) :

podman-compose -p chatbotaurus-vps1 -f podman-compose.yml up -d

Le plan mgaas-vps2 (passerelle et serveurs mcp-*) se lance de la même façon avec podman-compose.vps2.yml. Il n'est pas nécessaire pour ce tutoriel.

Téléchargez ensuite le modèle de dialogue souverain dans Ollama :

podman exec forge-ollama ollama pull cas/eurollm-1.7b-instruct-q8

3. Lancer le backend et le frontend

Appliquer les migrations :

cargo run -p forge-cli -- db migrate

Backend, port 3000 :

cargo run -p forge-api

Frontend, port 8080, dans un second terminal :

dx serve --platform web --port 8080 --package forge-ui

La première compilation wasm est longue. Ensuite le rechargement à chaud prend quelques secondes : ne relancez pas dx pour une modification.

Vérifiez que le backend répond (les autres sondes sont dans Diagnostics et signalement) :

curl http://localhost:3000/api/v1/health

La réponse est un JSON avec "status":"ok", le nom du service et la version.

4. Première conversation

1. Ouvrez l'interface locale (http://localhost:8080). Sans session, elle vous renvoie vers l'écran de connexion (/auth/login).
2. Créez un compte sur /auth/signup, puis connectez-vous sur /auth/login. Le code à usage unique arrive par courriel (/auth/verify-otp).
3. Au premier accès, l'assistant d'accueil (/onboarding) vous demande votre secteur et un modèle de départ. Voir Prise en main guidée.
4. Ouvrez /chat ou /orchestrator et posez une question, par exemple :

Quels connecteurs sont disponibles pour l'ERP ?

L'assistant s'appuie sur le catalogue de connecteurs de votre instance. La page est décrite dans Chat.

5. Interroger l'API

Les routes de l'API sont sous /api/v1. Le catalogue des connecteurs (contrat et authentification : Documentation Swagger) exige un jeton (Authorization: Bearer <jeton>), obtenu par la connexion (voir Authentification) :

curl -H "Authorization: Bearer <jeton>" \
  http://localhost:3000/api/v1/mcp/catalogue

Le transport MCP (JSON-RPC 2.0, HTTP streamable) est monté sur /api/v1/mcp, lui aussi authentifié. Voir Routes MCP.

Les passerelles (Routes des gateways et de la prédiction) se manipulent par /api/v1/mcp-gateway/*.

6. Vérifier

cargo test -p forge-replay
cargo build -p forge-ui --target wasm32-unknown-unknown --bin chatbotaurus

Pour regénérer ce livre en local : cargo run -p forge-docs. dx serve le sert ensuite sous /docs/.

En production

L'application publique est servie sur chatbotaurus.eu (site) et app.chatbotaurus.eu (application). Les prix publics sont sur la page /pricing : Starter 9 EUR, Pro 29,90 EUR, Enterprise 99,90 EUR par mois (HT), Souverain sur devis. Le détail des offres est dans Tarification.

Prochaines étapes

• Installation complète
• Prise en main guidée
• Fournisseurs de modèles
• Utiliser les connecteurs MCP
• Architecture
• Guide utilisateur
• Contribuer

Voir aussi

• Glossaire : les termes du livre (MCP, gateway, connecteur, nœud) définis en une ligne
• Problèmes connus : ce qui bloque fréquemment au premier lancement
• Fichiers de configuration : les fichiers que le code lit, au-delà du fichier d'environnement
• Gestion des conteneurs : commandes courantes une fois les plans démarrés

Cas d'usage par secteur

Chatbotaurus propose 16 secteurs préconfigurés, plus une entrée « Autre » pour les métiers qui n'y figurent pas. Chaque secteur associe un jeu de connecteurs de départ à un vocabulaire métier. Cette page reprend ces associations telles qu'elles sont décrites dans l'application ; les pages /solutions/<secteur> du site présentent les mêmes secteurs.

Comment lire cette page

• Dirigeant : repérez votre secteur dans le tableau et lisez la colonne « Pour quoi faire ».
• Responsable métier : le tableau des cas d'usage, plus bas, montre ce qu'on peut demander au chat et avec quels outils.
• Développeur : les connecteurs de départ du premier tableau sont ceux du catalogue (voir Vue d'ensemble des connecteurs). La colonne « Outils mobilisés » du second tableau cite aussi des services de la plateforme, par exemple CrowdSec, qui n'ont pas de fiche de connecteur.

Un secteur ne limite pas la plateforme : il choisit les connecteurs proposés par défaut. Vous pouvez ajouter ou retirer des connecteurs ensuite. Le secteur se choisit dans l'Orchestrateur (carte « Déployer les outils de votre métier »). L'assistant d'accueil le demande aussi (voir Prise en main guidée), mais le serveur n'en conserve rien aujourd'hui.

Les 16 secteurs

Chaque secteur est aussi relié à des catalogues de données publiques européennes (par exemple santé, énergie, industrie, agriculture, environnement) que le chat peut consulter en lecture (voir API-as-a-Service EU souverain).

Et si votre métier n'est pas dans la liste ?

L'entrée Autre décrit votre besoin et laisse l'équipe adapter les connecteurs, les workflows et la conformité à votre métier. Les secteurs de l'énergie, de l'informatique et de l'administration publique n'ont pas de parcours préconfiguré : ils passent par cette entrée, ou par le plan Souverain pour les exigences renforcées (voir plus bas).

Rappel pour les métiers de la santé

Les données de santé sont des données sensibles au sens de l'article 9 du RGPD. Les secteurs Thérapeute et Médical s'appuient sur des serveurs hébergés dans l'Union ; le secteur Médical ajoute un coffre de secrets (OpenBao et secrets) à ses connecteurs de départ. Le secrétariat de cabinet assisté ne fournit aucune aide au diagnostic et ne prend aucune décision médicale. Voir Conformité RGPD.

Les 13 cas d'usage transverses

Ces cas d'usage ne dépendent pas d'un secteur : chacun combine un modèle local (Fournisseurs de modèles), des connecteurs et, quand c'est utile, une base de recherche (Connaissances). Ils sont décrits sous /solutions/usecases/<cas>.

Ces cas d'usage assistent vos équipes : l'assistant propose, résume, alerte ; la décision, l'envoi et la validation restent à vos équipes. Une écriture sensible dans un outil (par exemple dans la comptabilité Odoo) passe par une approbation humaine (voir Workflows).

Exemple : un flux de commande en e-commerce

Avec le secteur E-commerce, un flux typique est le suivant :

1. Vous demandez au chat de chercher une commande ou un produit : l'assistant interroge Odoo (outils comme sales_order_search).
2. Vous lui demandez de créer un devis ou un contact : il propose l'écriture, que vous validez.
3. Un workflow n8n peut déclencher la suite (notification, relance) ; Mautic prend les campagnes, Matomo mesure l'audience.

Chaque étape utilise un connecteur réel du catalogue ; ce que vous automatisez ensuite dépend de votre configuration.

Quel plan choisir ?

Les plans (Starter, Pro, Enterprise, Souverain) se distinguent par le nombre de connecteurs, le niveau de support (SLA, support et niveaux de service) et le mode de déploiement. Le plan Souverain, sur devis, vise les banques et l'État : infrastructure dédiée isolée, déploiement isolé du réseau possible. Les prix et le détail de chaque plan sont sur la page de tarification du site et dans Tarification, seule source à jour.

Voir aussi

• Prise en main guidée — choisir son secteur dans l'assistant d'accueil, puis tester le chat.
• MCP et Orchestrateur — la Gateway Business, une carte par métier.
• Connecteur Odoo — le connecteur de départ commun à presque tous les secteurs.
• Comparatifs — pourquoi une passerelle hébergée dans l'UE plutôt qu'un SaaS hors UE.
• Questions fréquentes — les questions courantes d'un décideur avant de choisir.

Tarification et offres

Cette page décrit les quatre offres publiées sur la page Tarifs du site, état au 3 octobre 2026. Les prix sont hors taxes, mensuels et fixes. Le prix inclut la passerelle MCP, l'IA souveraine (Fournisseurs de modèles), les connecteurs MCP (Vue d'ensemble), la conformité UE (Conformité RGPD) et le support. Les outils métier (Odoo, n8n et autres) sont auto-hébergés par vos soins, ou disponibles en déploiement assisté, en option.

Le prix qui fait foi est celui de la page Tarifs et du contrat.

Les quatre offres

Chaque offre est décrite par son public et par ce qu'elle inclut.

Starter : 9 EUR par mois

Pour les TPE et les indépendants.

Pro : 29,90 EUR par mois

Pour les PME. C'est l'offre mise en avant sur la page.

Enterprise : 99,90 EUR par mois

Pour les ETI et les institutions.

Souverain : sur devis

Pour les banques et l'État.

Les délais de réponse du support, par sévérité et par offre, sont dans la page SLA. Trois jeux de délais coexistent sur le site : la page Tarifs affiche 48 h, 4 h et 1 h (Starter, Pro, Enterprise) ; la page SLA donne, pour les incidents critiques, 48 h, 8 h et 2 h en heures ouvrées ; le tableau des conditions générales donne 48 h, 24 h et 4 h ouvrées. La page Tarifs parle en outre d'un support 24/7 pour Enterprise, que les deux autres textes ne confirment pas (heures ouvrées). Le contrat fait foi.

Capacités par offre

La page Tarifs publie aussi une table « Capacités par plan » : 20 lignes, chacune avec le plan minimum qui débloque la capacité. Elle compte six niveaux (Essentiel, Starter, Pro, Business, Enterprise, Souverain) ; la grille de prix n'en publie que quatre, et Essentiel et Business n'y ont pas de prix. Chaque palier supérieur conserve les capacités des précédents. Cette table est lue dans un registre unique du dépôt (docs/audit/capacites-par-plan.yaml) : ce livre ne la recopie pas, pour ne pas dériver. Les sections du menu visibles par plan sont dans Tableau de bord.

Les limites chiffrées de chaque offre (douze ressources, énumérées dans Limites) sont lues en base.

Essai gratuit

D'après les conditions générales de vente :

• 14 jours, sans engagement et sans carte bancaire ;
• accès à l'ensemble des fonctionnalités de l'offre Pro ;
• à la fin, vous choisissez une offre ; sans souscription, le compte est désactivé et les données sont conservées 30 jours avant suppression définitive.

État du code au 3 octobre 2026 : ce parcours n'est pas câblé. L'inscription publique crée une organisation au plan « free » (un espace de travail, un workflow, un utilisateur et 100 conversations par mois), sans souscription ni essai de l'offre Pro. En terminant ou en passant l'assistant d'accueil, l'application pose pour une organisation sans souscription active une souscription simulée perpétuelle au niveau « essentiel » : jamais facturée, sans les fonctions de l'offre Pro. Tant que le code ne l'applique pas, lisez l'essai comme une promesse des conditions générales, pas comme une fonction de l'application.

Paiement et facturation

Comment choisir

• Indépendant ou TPE. Starter couvre l'essentiel avec 3 à 5 outils.
• PME avec une équipe. Pro apporte 10 outils et plus, l'IA avancée annoncée par la page Tarifs (ses moteurs de raisonnement sont en sommeil, voir plus haut) et une formation.
• ETI ou institution. Enterprise apporte une infrastructure dédiée et le code source transférable.
• Banque ou administration. Demandez un devis Souverain (voir aussi Cas d'usage par secteur).
• Vous hésitez. Les conditions générales prévoient un essai de 14 jours avec les fonctions de l'offre Pro (voir « Essai gratuit » plus haut : le code ne l'applique pas encore). Commencez par la prise en main guidée.

Le tarif agence est sur devis.

Voir aussi

• SLA, support et niveaux de service — disponibilité, délais de support et pénalités, par offre.
• Limites et ce que la plateforme ne fait pas — les quotas que chaque offre plafonne.
• Comparatifs — ce que le prix achète face aux autres familles d'offres.
• Tableau de bord — les sections du menu que chaque plan rend visibles.
• Questions fréquentes — « Est-ce gratuit ? » et l'essai de l'offre Pro.

SLA, support et niveaux de service

Cette page reprend la page publique « Accord de niveau de service » du site. Le texte qui fait foi est le contrat et les conditions générales de vente. En cas d'écart, ils priment sur ce livre.

Un SLA est ici un objectif contractuel sur les environnements de production sous contrat. Ce n'est pas une garantie sans condition.

Disponibilité

La disponibilité est mesurée chaque mois par le système de supervision de la plateforme (voir Supervision). Les maintenances programmées, annoncées 72 heures à l'avance, sont exclues du calcul.

Les conditions générales plafonnent les pénalités à 30 % du montant mensuel de l'abonnement concerné. L'avoir est proportionnel au temps d'indisponibilité.

Temps de réponse du support

Les temps sont en heures ouvrées : du lundi au vendredi, de 9 h à 18 h (CET).

L'offre Souverain relève d'un SLA personnalisé sous contrat. L'astreinte sur incidents P1 et P2 y est négociée au cas par cas.

L'assistant automatisé (niveau 1) est disponible à toute heure pour le premier tri. C'est un objectif : il suppose que l'API publique soit exposée.

Escalade

Communication des incidents

• La page de statut publique est /status.
• Un courriel automatique part pour les incidents P1 et P2.
• Un post-mortem est publié dans les 5 jours ouvrés suivant un incident P1 (voir Réponse aux incidents).
• Une violation de données est notifiée à la CNPD et aux clients sous 72 heures (article 33 du RGPD, article 23 de NIS2).

Reprise après incident

Ces cibles sont un programme, pas un constat. Aucune restauration chronométrée n'est encore publiée : le premier exercice daté fera passer la cible en résultat.

Le RPO de 24 heures vient du rythme des sauvegardes (Sauvegarde et restauration). Une perte allant jusqu'à une journée de données est donc possible.

Ce que le SLA ne couvre pas

• Les services tiers que vous connectez (votre Odoo, votre n8n).
• La force majeure, la maintenance programmée et l'usage non conforme.

Voir aussi

• Tarification — le contenu de chaque offre.
• Réponse aux incidents — sévérités et phases de la procédure interne.
• Sauvegarde et restauration — le rythme des sauvegardes dont découle le RPO.
• Limites et ce que la plateforme ne fait pas — les quotas par offre, à côté de la disponibilité.
• Supervision — ce que la supervision mesure réellement aujourd'hui.
• Questions fréquentes — à qui écrire quand un workflow ne répond plus.

Comparatifs

Cette page compare Chatbotaurus à deux familles d'offres, sans nommer de tiers. Elle suit la page publique « Comparatif souverain » du site, état au 3 octobre 2026.

Deux règles :

• on compare des critères que le code ou la configuration de la plateforme permettent de vérifier ;
• quand une capacité d'une autre offre n'est pas documentée publiquement, on écrit « non documenté », pas « absent ».

Les deux familles

Chatbotaurus est une passerelle MCP hébergée dans l'UE (voir Architecture Chatbotaurus), qui relie un assistant à vos outils métier (voir Vue d'ensemble). Ce n'est ni un assistant généraliste, ni un simple outil de flux.

Verdict critère par critère

« En option » veut dire désactivé par défaut. « En cours » veut dire prévu, pas livré.

Ce qui différencie la plateforme

• Routage déterministe. EntityRouter choisit le connecteur par des règles. Aucune mesure de latence du routage n'est publiée.
• Cryptographie en option. Quatre modules sont disponibles sur activation : ML-KEM-768 (canal hybride), compute-mode, preuves Schnorr, partage de secret de Shamir. Ils ne sont pas actifs par défaut (voir Glossaire, entrées PQC et Compute-mode).
• Voix européenne. La reconnaissance vocale (Voix et Canaux) couvre 7 langues.
• Catalogue de connecteurs. 195 fiches de connecteurs, dont le connecteur Odoo à 711 outils au registre.

Ce que la comparaison ne dit pas

• Elle ne mesure ni la qualité des réponses, ni la vitesse d'un autre produit.
• Elle ne compare pas les prix publics d'un tiers : ils changent et ne sont pas dans notre code.
• Elle ne vaut pas certification. La plateforme est conçue pour répondre au RGPD, à NIS2 et à l'AI Act, et ne détient aucune certification à ce jour.

Voir aussi

• Tarification : les offres et leurs prix.
• Limites : ce que la plateforme ne fait pas.
• Migration : passer d'un outil d'automatisation à Chatbotaurus.
• Conformité RGPD : le détail réglementaire.
• SLA, support et niveaux de service : disponibilité et support, par offre, avec leurs pénalités.
• Questions fréquentes : « Pourquoi pas une offre SaaS d'IA hors UE ? » en réponse courte.
• SSO Authentik : l'authentification unique européenne citée dans le verdict.

Limites et ce que la plateforme ne fait pas

Cette page dit ce que Chatbotaurus fait, ce qu'il ne fait pas, et les limites mesurées dans le code. Les valeurs sont celles par défaut au 3 octobre 2026. Un opérateur qui héberge sa propre instance peut en régler certaines par variable d'environnement.

Ce que la plateforme fait

Ce que la plateforme ne fait pas

• Ce n'est pas un chatbot généraliste. Le chat de support répond aux questions sur la plateforme. Il ne tient pas de conversation libre sans contexte métier.
• Ce n'est pas un ERP. Elle se connecte à Odoo ou à un autre outil ; les données métier restent dans cet outil.
• Ce n'est pas un hébergeur web. Elle n'héberge ni site, ni application, ni base de données générique.
• Ce n'est pas un stockage de fichiers. Les documents vivent dans les outils connectés.
• Elle n'exécute pas de code JavaScript dans un workflow. Les nœuds « fonction personnalisée » sont refusés à l'exécution (doctrine Rust uniquement ; voir Migration depuis d'autres outils).
• Elle ne route pas vers des services hors UE. À l'exécution, les identifiants de serveur de 25 services hors UE sont refusés, et seuls les serveurs de la liste autorisée sont appelés (voir Conception des connecteurs MCP).

Limites de débit

Le débit est limité par adresse IP. Au-delà, l'API répond 429 (format des erreurs : Documentation Swagger).

Le chat public du site a un seau à part, parce qu'une réponse coûte 20 à 36 secondes de calcul au modèle local (mesure du 3 octobre 2026).

La connexion a ses propres limites, par compte et par adresse : au-delà d'un nombre d'échecs, l'adresse est bloquée pendant un temps réglable (voir Sécurité).

Taille des requêtes

Au-delà, l'API répond 413.

Quotas par offre

Le code sait plafonner douze ressources : espaces de travail, workflows, utilisateurs, conversations par mois, connecteurs, serveurs MCP, connecteurs par gateway, appels d'API, stockage (en Go), minutes de voix, lignes d'appel concurrentes et enregistrements vectoriels. Les valeurs sont lues en base, par offre ; une valeur vide veut dire illimité.

• Un quota atteint répond 402 avec le code QUOTA_EXCEEDED et un lien de montée en gamme.
• Un quota que la plateforme n'a pas pu mesurer répond 503, jamais « illimité ».

La table des capacités par offre est sur la page Tarification.

Langues

Limites de l'IA

• Erreurs possibles. Un modèle peut se tromper. L'ancrage dans vos documents (RAG, voir Connaissances) réduit les erreurs, il ne les supprime pas. Vérifiez les informations critiques.
• Latence. Sur processeur seul, une réponse du modèle local (Fournisseurs de modèles) peut prendre de 20 à 36 secondes (chat public, mesure du 3 octobre 2026).
• Pas d'analyse d'images. Aucune analyse d'image ni de page scannée n'est annoncée. La recherche visuelle de pages est hors périmètre (spec 115).
• Pas de GPU. L'inférence se fait sur processeur. Aucune tâche de spec ne prévoit de GPU ; tout achat de GPU est soumis à validation (spec 68, DEC-68-004).

Prévu

Ce qui n'a pas de tâche dans une spec n'est pas annoncé ici.

Voir aussi

• Tarification et offres — les capacités par plan que ces quotas chiffrent.
• SLA, support et niveaux de service — disponibilité et délais de support, par offre.
• Gestion des erreurs — le format des erreurs de l'API et le code de limite de débit.
• Questions fréquentes — « Mon workflow ne fonctionne pas » : lire un 429 ou un 402.
• Comparatifs — ce que la plateforme est, face aux autres familles d'offres.

Installation de Chatbotaurus

Ce guide installe Chatbotaurus en développement local. La pile est écrite en Rust : forge-api (Axum, SeaORM) pour le backend et forge-ui (Dioxus 0.7) pour l'interface. Pour aller plus vite, voir le démarrage rapide.

Ce guide ne couvre pas l'installation sur un serveur : pour la production (réseaux, volumes, unités Quadlet, mise à jour), voir Déploiement avec Podman.

Prérequis

Le chemin de référence du dépôt est Windows (PowerShell) : les lanceurs de développement sont des scripts .ps1. Sous Linux ou macOS, utilisez les commandes cargo et dx ci-dessous.

1. Cloner le dépôt

git clone <url-du-depot>
cd <dossier-du-depot>

2. Compiler le workspace

cargo build --workspace

Le workspace compte 20 crates (forge-core, forge-api, forge-ui, forge-auth, forge-db, forge-mcp, forge-cli, forge-gateway, forge-voice, forge-ops, forge-audit, forge-docs, entre autres). Une première compilation à froid est longue.

3. Configurer l'environnement

cp .env.example .env

Les valeurs secrètes de .env.example sont des gabarits CHANGE_ME_... que l'application refuse au démarrage : remplacez-les. Pour générer un secret : openssl rand -hex 64.

Variables essentielles (chacune est lue par le code, voir crates/forge-core/src/config.rs) :

# Backend
PORT=3000
DATABASE_URL=postgresql://<utilisateur>:<mot-de-passe>@localhost:5432/<base>
REDIS_URL=redis://localhost:6380
JWT_SECRET=<secret-genere>
AT_REST_ENCRYPTION_KEY=<secret-genere>

# Vecteurs et secrets
QDRANT_URL=http://localhost:6334
BAO_ADDR=http://localhost:8200

# Modèles (Ollama)
OLLAMA_BASE_URL=http://localhost:11434

# Courriel (second facteur par code)
SMTP_HOST=<serveur-smtp>
SMTP_PORT=587
SMTP_USER=<compte>
SMTP_PASSWORD=<mot-de-passe-applicatif>
SMTP_FROM=<adresse-expediteur>

# SSO OIDC (Authentik), facultatif
AUTHENTIK_SERVER_URL=http://localhost:9000
AUTHENTIK_CLIENT_ID=<identifiant-client>
AUTHENTIK_CLIENT_SECRET=<secret-client>

# Journalisation
RUST_LOG=info,forge_api=debug

Notes (la liste complète des variables est dans Variables d'environnement) :

• FORCE_2FA vaut vrai par défaut : le démarrage exige alors SMTP_HOST.
• AT_REST_ENCRYPTION_KEY chiffre les identifiants stockés ; sans elle, la clé dérive de JWT_SECRET.
• .env doit être lisible par dotenvy : une valeur contenant un espace doit être entre guillemets, sinon tout le fichier est ignoré.
• Il n'existe pas de variables CSRF_SECRET ni TOTP_ISSUER.

4. Démarrer l'infrastructure

podman-compose -p chatbotaurus-vps1 -f podman-compose.yml up -d

Ce plan (détail dans Déploiement avec Podman) démarre PostgreSQL, Valkey, Qdrant, Ollama, Authentik, OpenBao, les services de voix et l'observabilité. Le second plan, mgaas-vps2 (podman-compose.vps2.yml), porte la passerelle et les serveurs mcp-*. Tout service futur y est ajouté dans ce fichier, jamais lancé à la main.

Vérifiez que les conteneurs tournent avec podman ps (voir Gestion des conteneurs). Si l'un d'eux manque, voir Problèmes connus. Téléchargez aussi les modèles de dialogue avant la première conversation (section « Modèles » plus bas).

5. Initialiser la base

Les migrations s'appliquent aussi au démarrage de forge-api. Pour migrer sans lancer le serveur :

cargo run -p forge-cli -- db migrate

6. Lancer en développement

Backend, port 3000

cargo run -p forge-api

Sous Windows, le lanceur de référence est scripts/dev/run-forge-api.ps1. Il copie le binaire avant de le lancer (la compilation reste possible pendant que le serveur tourne) et exige la variable ADMIN_PASSWORD (12 caractères ou plus) :

$env:ADMIN_PASSWORD = "<mot-de-passe-admin-12-caracteres-ou-plus>"
powershell -File scripts\dev\run-forge-api.ps1

scripts/dev/watch-forge-api.ps1 recompile et remplace le binaire à chaque modification du backend.

Routes principales (contrat complet : Documentation Swagger) :

• GET /api/v1/health et GET /api/v1/healthz : état du service.
• GET /api/v1/readyz : base et Valkey joignables.
• POST /api/v1/predictions et POST /api/v1/predictions/stream : inférence.
• GET /api/v1/mcp/catalogue : catalogue des connecteurs (authentifié).
• POST /api/v1/mcp : transport MCP (authentifié).

Frontend, port 8080

dx serve --platform web --port 8080 --package forge-ui

Sous Windows : pwsh -File scripts\dev\run-dx.ps1. Ce lanceur utilise un répertoire de build séparé (target-dx) pour que cargo build ne bloque pas dx. dx recharge à chaud : ne le relancez pas pour un changement de code. pwsh -File scripts\dev\run-dx.ps1 -Status donne l'état du serveur.

Ouvrez l'interface locale (http://localhost:8080).

Autres plateformes

forge-ui se compile pour les cibles de Dioxus (web, desktop, android, ios, server, liveview), par exemple :

dx serve --platform desktop --package forge-ui

La cible web est la seule suivie en continu.

Ce livre

cargo run -p forge-docs               # construit le livre et le copie dans forge-ui/public/docs
cargo run -p forge-docs -- --clean    # purge book/ et public/docs/ avant de construire

dx serve sert ensuite le livre sous /docs/. L'option --serve (aperçu avec rechargement) n'existe pas : le binaire n'accepte que --src, --dst, --clean, --no-copy et --keep-html-urls.

Modèles

Le dialogue utilise EuroLLM 1.7B, avec ministral-3:3b en repli. Le modèle d'embedding (384 dimensions) est chargé par fastembed dans le processus forge-api : il ne passe pas par Ollama. Détails dans Fournisseurs.

podman exec forge-ollama ollama pull cas/eurollm-1.7b-instruct-q8
podman exec forge-ollama ollama pull ministral-3:3b

Vérification

curl http://localhost:3000/api/v1/health
cargo test -p forge-replay
cargo test -p forge-api

La première commande rend un JSON avec "status":"ok" (le même que dans le démarrage rapide) ; les deux suivantes doivent se terminer sans test en échec.

La CI (voir Contribuer) exécute aussi cargo clippy --workspace -- -D warnings et cargo fmt --check.

Prochaines étapes

• Configurer les fournisseurs de modèles
• Démarrage rapide
• Architecture
• Utiliser les connecteurs MCP

Voir aussi

• Prise en main guidée : créer le compte et tester le chat une fois la pile lancée
• Déploiement avec Podman : passer du développement local aux unités Quadlet
• Problèmes connus : pannes fréquentes au démarrage : Podman, Ollama, OpenBao, Authentik
• Diagnostics et signalement : vérifier chaque service après le démarrage

Prise en main guidée

Ce guide va de la création du compte au premier workflow. Chaque étape dit à qui elle s'adresse.

Quel est votre profil ?

• Dirigeant ou décideur : étapes 1, 2 et 8.
• Responsable métier : étapes 1 à 4, 6 et 7.
• Développeur ou intégrateur : toutes les étapes, surtout 3, 5 et 6.
• Administrateur système : étapes 3, 5 et 8, puis déploiement Podman.
• Délégué à la protection des données : conformité RGPD.

Étape 1 : créer le compte

Tous les profils

1. Ouvrez /auth/signup sur votre instance (en local : http://localhost:8080).
2. Renseignez les champs demandés et validez.
3. Connectez-vous sur /auth/login.
4. Saisissez le code à usage unique reçu par courriel (/auth/verify-otp). Le second facteur est actif par défaut (FORCE_2FA).
5. À la première connexion, l'assistant d'accueil s'ouvre (étape suivante). Si la connexion échoue, voir Questions fréquentes (« Comment me connecter ? »).

Les conditions générales prévoient un essai gratuit de 14 jours, sans engagement et sans carte bancaire. Il donne accès à l'ensemble des fonctionnalités de l'offre Pro. Sans souscription à la fin de l'essai, le compte est désactivé et les données sont conservées 30 jours avant suppression.

Étape 2 : l'assistant d'accueil

Tous les profils

À la première connexion, l'application ouvre /onboarding. L'assistant vous fait choisir :

Terminer l'assistant vous amène au tableau de bord (/dashboard). Aujourd'hui, le serveur ne retient de l'assistant que le fait de l'avoir terminé ou passé : langue, secteur, adresse Odoo et modèle de départ ne sont pas enregistrés, et l'organisation reçoit le niveau « essentiel » si elle n'a aucune souscription (voir Tarification). Prenez cinq minutes pour parcourir les pages principales :

Étape 3 : enregistrer vos identifiants

Développeur, administrateur système, responsable métier

Les identifiants permettent à Chatbotaurus de se connecter à vos outils (la page est décrite dans Sécurité et identifiants).

1. Ouvrez /credentials. Dans le menu, la page est dans la section Sécurité, visible à partir du plan Business ; sur un plan inférieur, ouvrez-la par son adresse (voir la section Navigation du Tableau de bord).
2. Cliquez sur la carte du service voulu (Odoo, n8n, Matomo, Nextcloud, entre autres).
3. Remplissez le formulaire : adresse du serveur, identifiant, clé d'API ou mot de passe applicatif selon le service.
4. Enregistrez.

Les identifiants sont chiffrés au repos en base (clé AT_REST_ENCRYPTION_KEY). Ils ne sont jamais réaffichés en clair : en modification, un champ secret laissé vide ou inchangé conserve la valeur enregistrée. Voir aussi OpenBao et gestion des secrets pour les secrets d'infrastructure.

Pour Odoo, le parcours complet (les quatre champs à renseigner, puis un premier appel d'outil) est dans Connecter Odoo à la passerelle MCP.

Étape 4 : tester le chat

Tous les profils

1. Ouvrez /chat.
2. Posez une question simple : « Bonjour, que sais-tu faire ? »
3. Observez la réponse. La page est décrite dans Chat.

Le chat parle à un workflow déployé : si le sélecteur de workflow est vide, créez d'abord un workflow (étape 6), puis revenez à cette étape.

Si un identifiant Odoo est enregistré, posez une question métier, par exemple « Combien de contacts dans le CRM ? ». Le registre d'outils Odoo compte 711 outils (mesure du 3 octobre 2026, odoo_tools_registry.rs).

Le modèle de dialogue par défaut est EuroLLM 1.7B, exécuté localement via Ollama, avec ministral-3:3b en repli. Il tourne sur le processeur : les réponses longues prennent quelques secondes. Pour utiliser un autre fournisseur, voir Fournisseurs.

Étape 5 : parcourir le catalogue de serveurs MCP

Développeur, administrateur système

Ouvrez /mcp-servers. Le catalogue se filtre par secteur et par catégorie (voir MCP et Orchestrateur). Le catalogue public compte 108 entrées dont 15 marquées « disponibles » (mesure du 3 octobre 2026) ; la page de l'application en liste 175.

Le déploiement en un clic n'est pas encore câblé. Les actions déployer, démarrer, arrêter et redémarrer un serveur du catalogue répondent 503 FEATURE_PENDING tant que l'adaptateur Podman n'est pas branché sur forge-api. C'est prévu (spec 16, tâche P5.5, route prévue ops/deploy). En attendant, un serveur se lance par le plan compose mgaas-vps2 (podman-compose.vps2.yml). Consulter le catalogue est possible dès maintenant (voir parcourir le catalogue de services).

Pour les dirigeants : cette étape relève de votre équipe technique.

Étape 6 : créer votre premier workflow

Responsable métier, développeur

Un workflow est une suite d'actions que vous assemblez sur un canvas (voir Workflows).

1. Ouvrez /workflows et créez un nouveau workflow.
2. Placez un nœud d'entrée (MCP Start) sur le canvas.
3. Ajoutez un nœud agent.
4. Ajoutez un nœud de sortie (MCP End).
5. Reliez les nœuds en tirant des lignes.
6. Configurez l'agent : modèle et consigne système.
7. Enregistrez, puis testez depuis /chat.

Un nœud est une brique du workflow. Un agent est un nœud qui s'appuie sur le modèle. Un connecteur est un nœud qui parle à un outil externe (Odoo, n8n, entre autres). Voir le glossaire.

Étape 7 : intégrer le chat à votre site

Développeur, responsable métier

1. Ouvrez /embeds : la page liste vos workflows.
2. Choisissez celui à publier ; le générateur d'intégration s'ouvre.
3. Réglez l'apparence (couleurs, message d'accueil).
4. Copiez le code généré et collez-le dans votre site.

Le code est un extrait <script> qui s'ajoute à n'importe quel site. Voir aussi Voix et Canaux pour la page Marque (widget).

Étape 8 : passer à une offre payante

Dirigeant, administrateur

Les prix publics sont sur la page /pricing. Tous sont HT et mensuels.

Le détail des offres et des capacités par plan est sur /pricing et dans la page Tarification, les délais de support dans SLA. La gestion de l'abonnement est sur /billing (voir Paramètres).

Liste de contrôle

Et ensuite

• Guide utilisateur
• Cas d'usage par secteur
• FAQ
• Une question : la page /contact de votre instance

Voir aussi

• Fournisseurs de modèles : changer de modèle ou brancher un fournisseur européen
• Utiliser les connecteurs MCP : où vivent les fiches et comment le catalogue est lu
• Glossaire : nœud, agent, connecteur, gateway : les termes définis
• Limites et ce que la plateforme ne fait pas : quotas par offre et limites de débit

Fournisseurs de modèles

Chatbotaurus répond par défaut avec un modèle souverain européen exécuté localement. Un fournisseur supplémentaire se branche par un identifiant (voir Sécurité et identifiants) enregistré dans l'application, pas par une variable d'environnement globale.

Les trois modèles souverains

La liste est dans crates/forge-core/src/model_governance.rs (SOVEREIGN_LOCAL_MODELS). C'est l'unique source des défauts du code.

Télécharger les deux modèles de dialogue (le conteneur Ollama vient du plan décrit dans Déploiement avec Podman) :

podman exec forge-ollama ollama pull cas/eurollm-1.7b-instruct-q8
podman exec forge-ollama ollama pull ministral-3:3b

Le modèle d'embedding n'est pas un modèle Ollama : ollama pull ne le concerne pas. fastembed le télécharge dans son cache au premier usage (le pipeline d'indexation est décrit dans Connaissances). La collection Qdrant du pipeline wiki est donc créée en 384 dimensions.

Ollama local (par défaut)

OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=ministral-3:3b
OLLAMA_EMBEDDING_MODEL=paraphrase-multilingual-MiniLM-L12-v2

Valeurs par défaut (crates/forge-core/src/config.rs) : OLLAMA_BASE_URL vaut http://localhost:11434 et OLLAMA_MODEL prend le modèle de repli de la liste souveraine. Le délai d'appel (OLLAMA_TIMEOUT_SECS) vaut 120 s.

Ajouter un autre fournisseur

La résolution du modèle de chat d'une organisation suit cet ordre (crates/forge-api/src/routes/llm_provider.rs) :

1. le dernier identifiant de type IA enregistré par l'organisation ;
2. l'ancienne configuration /llm-provider (compatibilité) ;
3. EuroLLM en local.

Pour ajouter un fournisseur :

1. Ouvrez /credentials (section Sécurité du menu à partir du plan Business, sinon par son adresse) et choisissez la catégorie des modèles de langage.
2. Choisissez la famille (par exemple mistralApi pour Mistral AI, France, ou ollama pour votre propre serveur Ollama). Le formulaire préremplit l'adresse et le modèle.
3. Pour un serveur auto-hébergé, indiquez son adresse de base. Pour un service en ligne, saisissez la clé d'API.
4. Enregistrez. La carte active est signalée dans la liste.
5. Vérifiez dans le chat : si le fournisseur est refusé, le chat répond avec EuroLLM (voir « Fournisseurs refusés » plus bas).

La clé n'est stockée qu'une fois, chiffrée en base. Le fournisseur choisi n'est utilisé que si son point d'accès est local ou européen (voir « Fournisseurs refusés »). Les variables LLM_PROVIDER et MISTRAL_API_KEY du fichier .env.example ne sont pas lues par le backend pour choisir le fournisseur de chat : n'en dépendez pas.

Les métadonnées du code (llm_provider_metadata.rs) décrivent Ollama et Mistral AI comme fournisseurs européens. Des fiches ollama et localai existent dans connectors/.

Fournisseurs refusés

Avant chaque appel à un modèle, le code applique deux contrôles (assert_llm_sovereign, crates/forge-core/src/agent/memory/sovereignty.rs) :

1. le nom du modèle ne doit contenir aucun de ces huit noms : OpenAI, Anthropic, Azure, Google, AWS, Bedrock, Cohere, Groq (US_PROVIDERS) ;
2. l'adresse du point d'accès doit être locale (boucle locale, réseau privé), se terminer par .eu, ou être celle d'un fournisseur européen connu (Ollama, Mistral AI et un hébergeur européen référencé dans le code).

Un appel qui échoue l'un des deux contrôles est refusé avant l'envoi du message. Quand le fournisseur choisi par l'organisation est refusé, le chat bascule sur EuroLLM. La liste de dix noms LLM_PROVIDER_US_BLOCKLIST (avec Together et Replicate) existe dans le code mais aucun chemin de production ne l'appelle.

La liste des familles proposées dans /credentials évolue : certaines familles passent par un agrégateur ou un service hors UE. Le formulaire affiche l'origine de chaque famille. Une famille dont le point d'accès n'est ni local ni européen s'enregistre, mais ses appels sont refusés par le contrôle ci-dessus.

Voir aussi

• Installation : compiler et lancer la pile en local
• Variables d'environnement : chaque variable lue par le code
• Conformité RGPD : données personnelles, hébergement et sous-traitants dans l'UE
• Chat : quel modèle répond, et le repli quand un fournisseur est refusé
• Conception des connecteurs MCP : le contrôle de conformité UE appliqué aux connecteurs
• Questions fréquentes : « Quels modèles d'IA sont utilisés ? » en une réponse courte

Utiliser les connecteurs MCP

Chatbotaurus utilise le Model Context Protocol (MCP) pour parler à des services externes. Un connecteur expose des outils que l'agent peut appeler.

Où vivent les connecteurs

Le dossier connectors/ compte 195 fiches YAML (mesure du 3 octobre 2026). Ajouter un outil HTTP se fait en ajoutant une fiche, sans écrire de Rust. Voir Créer votre premier connecteur MCP.

Exemples de fiches présentes

Chaque nom ci-dessous correspond à un fichier de connectors/.

Pour l'ERP, odoo porte un registre de 711 outils (mesure du 3 octobre 2026) et un client XML-RPC. Voir Connecter Odoo à la passerelle MCP et la vue d'ensemble des connecteurs.

Le nombre de fiches n'est pas le nombre de services prouvés. Le catalogue public compte 108 entrées, dont 96 avec une fiche et 15 marquées « disponibles » (mesure du 3 octobre 2026).

Identifiants

Un connecteur lit ses secrets au moment de la requête, depuis les identifiants enregistrés sur /credentials (chiffrés en base, voir Sécurité et identifiants). Ne placez jamais une clé dans une fiche YAML : une fiche référence une variable, par exemple ${NOM_DE_VARIABLE}.

Transport MCP

Le backend expose le transport HTTP streamable (voir Architecture Chatbotaurus). La version de protocole courante du code est 2025-03-26. La route est authentifiée :

POST   /api/v1/mcp   -> JSON-RPC 2.0 (initialize, tools/list, tools/call)
GET    /api/v1/mcp   -> flux SSE de notifications
DELETE /api/v1/mcp   -> fermer la session

La session est portée par l'en-tête Mcp-Session-Id. Le transport est actif si MCP_ENABLED et API_ENABLED le sont. Voir Routes MCP.

Consulter le catalogue par l'API

Le jeton s'obtient par la connexion : voir Authentification.

# Connecteurs chargés par l'instance (jeton requis)
curl -H "Authorization: Bearer <jeton>" \
  http://localhost:3000/api/v1/mcp/catalogue

# Une entrée
curl -H "Authorization: Bearer <jeton>" \
  http://localhost:3000/api/v1/mcp/catalogue/<identifiant>

La famille /api/v1/mcp-gateway/* (par exemple /mcp-gateway/servers) porte la passerelle (Routes des gateways et de la prédiction). Le catalogue d'applications métier (Routes du catalogue métier) est sous /api/v1/mcp/catalog-business.

Déploiement : pas encore. Les routes deploy, start, stop, restart, security et secrets de /api/v1/mcp/catalog-business/{id}/... répondent 503 FEATURE_PENDING avec un en-tête Retry-After à un administrateur (un autre rôle reçoit 403, sauf security qui répond 503 à tout rôle). Elles attendent l'adaptateur Podman de forge-api (spec 16, tâche P5.5). Il n'existe pas de route /mcp/gateways/<nom>/deploy. Pour lancer un serveur aujourd'hui, utilisez le plan compose mgaas-vps2.

Voir aussi

• Parcourir le catalogue de services et préparer un déploiement : ce qui marche et ce qui est en sommeil
• Conception des connecteurs MCP : manifestes YAML, connecteurs natifs et contrôle de conformité UE
• Connecteur Odoo : le connecteur qui porte le registre d'outils nommés et génériques
• MCP et Orchestrateur : les catalogues de serveurs tels que l'application les montre
• Déploiement avec Podman : lancer le plan client qui porte les serveurs
• Fichiers de configuration : la structure des manifestes de connecteurs

Tableau de bord

Le tableau de bord (/dashboard) est la première page après la connexion. Il résume l'activité de votre espace de travail : vos workflows, vos exécutions, vos premiers pas.

Se connecter

Toute page de l'application exige une session. Sans session, vous êtes renvoyé vers l'écran de connexion (/auth/login).

L'écran de connexion offre deux voies :

• courriel et mot de passe, suivis d'un second facteur quand il est actif pour votre compte : code reçu par courriel, ou code de votre application d'authentification (TOTP, voir Paramètres) ;
• le bouton « Authentik SSO » (connexion unique).

Voir SSO Authentik pour la configuration côté administrateur.

Ce que vous voyez, de haut en bas

Un compteur ou une carte qui ne peut pas être lu affiche zéro ou un tiret : une seule lecture en échec ne vide pas toute la page.

Navigation

La barre latérale et la barre haute affichent le même modèle : une catégorie par section, puis les pages de la section. Les sections visibles dépendent de votre plan.

Essentiel et Business sont des niveaux de la table des capacités par plan ; la page Tarifs ne publie pas de prix pour eux (voir Tarification). La section Paramètres est visible à tous les plans. Les pages d'administration /admin* n'apparaissent qu'aux comptes administrateur. Un plan inférieur peut encore ouvrir une page par son adresse : la limite porte sur le menu, et l'API applique ses propres refus (voir Limites et ce que la plateforme ne fait pas).

Source de ce tableau : docs/audit/nav-par-tier.yaml.

Voir aussi

• Chat : parler à un workflow déployé
• Workflows : l'éditeur, la palette de nœuds, les exécutions
• Paramètres : réglages, facturation, compte et gestion des utilisateurs
• MCP et Orchestrateur : la saisie du tableau de bord ouvre l'Orchestrateur
• Analytique : les cartes Leads et Appels renvoient à ces pages
• Prise en main guidée : les étapes « Pour démarrer », une à une
• Tarification et offres : les capacités par plan derrière les sections visibles

Workflows

Un workflow est une suite de nœuds qui relie un message à des actions : appeler un outil, un modèle, un autre service. Les pages ci-dessous servent à les créer, les déployer et suivre leurs exécutions.

Les pages

La page Exécutions n'a pas d'entrée dans la barre latérale. On l'ouvre depuis le lien « Voir tout » du tableau de bord, ou par son adresse.

Liste des workflows

Le bouton « Nouveau workflow » en crée un et ouvre l'éditeur. Le menu de chaque carte propose : modifier, dupliquer, générer le script d'intégration (voir l'étape 7, « intégrer le chat à votre site », de la prise en main guidée), supprimer.

Éditeur

L'éditeur a trois zones :

• à gauche, la palette de nœuds, classée par catégorie ;
• au centre, le canevas où l'on dépose et relie les nœuds ;
• à droite, le panneau de propriétés du nœud choisi.

Vous pouvez enregistrer, déployer ou mettre en pause, supprimer, et annuler ou refaire (Ctrl+Z, Ctrl+Y). Un nœud choisi a une adresse partageable : /workflows/<id>/nodes/<nœud>.

Palette de nœuds

La palette compte 9 catégories et 74 nœuds. Un nœud grisé ne peut pas être déposé dans un workflow : il sert de brique interne à l'agent.

Deux précisions :

• le nœud « MCP FHE Processor » et le nœud « MCP FHE Security » ne font pas de chiffrement homomorphe. Ils déchiffrent, calculent et rechiffrent en AES-256-GCM côté serveur. Le catalogue le dit lui-même ;
• le nœud « MCP LLM » appelle un modèle de langage local (voir Fournisseurs de modèles). Son modèle par défaut est ministral-3:3b, modifiable dans ses propriétés. Le fournisseur refuse un modèle hors du périmètre souverain (voir Chat pour le modèle du chat).

Versioning

La page liste vos workflows avec leur type, leur état (déployé ou brouillon) et leurs dates de création et de mise à jour. Elle n'enregistre pas d'historique de versions et n'a pas de numéro de version : le serveur n'en garde aucun.

Exécutions

Le tableau a cinq colonnes : Statut, Gateway, Entrée, Durée, Date. Une recherche filtre la liste. Ouvrir une ligne montre le déroulé du graphe : pour chaque nœud, OK ou ECHEC, son nom et l'erreur éventuelle.

Connexion aux services

Les workflows appellent vos services par les connecteurs MCP (identifiants : Sécurité et identifiants). Le dépôt décrit 195 connecteurs (fichiers connectors/*.yaml). Tous ne sont pas déployés : un connecteur n'est dit « opérationnel » que s'il a été prouvé avec des données réelles. Voir la liste des connecteurs.

Pages annoncées, non disponibles

Les adresses /workflows/folders, /workflows/tags, /workflows/notes et /workflows/sharing affichent « Fonctionnalité v2.1 » : le dossier, l'étiquette, la note et le partage par workflow sont planifiés pour la v2.1. D'ici là, les droits se règlent au niveau de l'espace de travail (voir Paramètres).

Voir aussi

• MCP et Orchestrateur : l'assistant qui construit vos workflows et les catalogues de serveurs MCP
• Analytique : l'usage de l'agent et la qualité de ses réponses, en chiffres
• Chat : tester un workflow déployé en lui parlant
• Migration depuis d'autres outils : l'équivalent de chaque concept d'un autre outil en nœud MCP
• Routes des gateways et de la prédiction : un workflow est une gateway pour l'API
• Questions fréquentes : « Mon workflow ne fonctionne pas », l'ordre des vérifications

Chat

La page Chat (/chat) est l'endroit où vous parlez à un de vos workflows déployés. Il faut d'abord en avoir créé un : voir l'étape 6 de la prise en main guidée.

Une page, trois onglets

La page /chat porte trois onglets. Chacun a aussi sa propre adresse.

Gateway Chat

• Choix du workflow : un sélecteur en haut choisit le workflow qui répond.
• Liste des conversations : nouvelle conversation, recherche, favoris, dossiers, renommer, dupliquer, supprimer. Les favoris, dossiers et noms sont gardés dans votre navigateur.
• Saisie : texte, ou micro pour dicter (la reconnaissance vocale est décrite dans Voix et Canaux).
• Outils utilisés : quand l'agent appelle un outil, la réponse l'indique.
• Export : une conversation s'exporte en JSON ou en Markdown.
• Serveurs MCP : le menu du sélecteur propose six serveurs à activer ou non (Odoo, n8n, Matomo, un agenda, CryptPad, Jitsi).

Comment une réponse est produite

1. Le routeur déterministe (EntityRouter) analyse votre message. Quand sa confiance atteint 0,80 ou plus, il appelle l'outil lui-même et formate le résultat. Aucun modèle de langage ne décide dans ce cas.
2. Sinon, la question passe au modèle de langage local.
3. Un outil irréversible ne s'exécute pas seul : le chat crée une demande d'approbation, qu'un humain décide ensuite.

Quel modèle

Le choix des outils, lui, reste celui du routeur déterministe. Pour brancher un autre fournisseur, voir Fournisseurs de modèles.

Contrôles de réponse

Un moteur anti-hallucination existe (validation multicouche, recherche de sources). Il démarre seulement si la recherche vectorielle (Connaissances) et Ollama sont disponibles. Le moteur de vérification factuelle « GroundingEngine » est dans le code mais n'est pas branché : /mgaas/engines le déclare « dormant ». N'attendez donc pas une vérification factuelle automatique de chaque réponse.

Historique

La page liste vos conversations et leurs messages. Elle sert aussi de page seule (/chat-history).

Messages proactifs

La page permet de créer, activer, modifier et supprimer des règles. Une règle porte un déclencheur (temps passé sur la page, profondeur de défilement, intention de sortie, inactivité, page visitée, horaire), une audience et un workflow. Le déclenchement côté visiteur n'est pas couvert par ce chapitre.

Voir aussi

• MCP et Orchestrateur : l'assistant qui construit vos workflows et les catalogues de serveurs MCP
• Voix et Canaux : la reconnaissance vocale, le widget et les canaux de diffusion
• Workflows : le workflow choisi dans le sélecteur se construit ici
• Analytique : l'historique des conversations et les messages proactifs en chiffres
• Routes des gateways et de la prédiction : la même conversation, par l'API
• Limites et ce que la plateforme ne fait pas : latence du modèle local et limites de débit du chat
• Questions fréquentes : « Mon workflow ne fonctionne pas », l'ordre des vérifications

Connaissances

La section Connaissances regroupe ce que votre agent peut retrouver : collections de documents, fichiers, outils personnalisés, wiki. Le principe du RAG est défini dans le Glossaire. Aujourd'hui, l'application affiche et gère les collections ; l'ajout de documents depuis l'interface n'est pas encore branché (détail plus bas).

Les pages

Les plans Essentiel n'affichent que Collections et Fichiers. Les autres pages apparaissent à partir du plan Starter (voir Tarification et offres).

Collections

La page liste vos collections avec quatre compteurs (collections, documents, morceaux, synchronisées). Une collection se crée, se modifie, se duplique, se supprime. Supprimer demande de retaper le nom.

Ouvrir une collection mène à /document-stores/<id>, une page à quatre onglets : Documents, Configuration, Preview, Vector Store. Cette page de détail est aujourd'hui une coquille avec des données d'exemple. Le bouton d'ajout de document propose cinq onglets (Fichier, URL, Sitemap, Table, Configuration), mais son envoi n'est pas branché.

Ce que l'API ne fait pas encore

Ces appels de l'API (Routes des ressources) répondent 503 FEATURE_PENDING : traiter un document (loader/process), l'envoyer par URL (loader/upload-url), l'envoyer en table (loader/upload-table), supprimer ou remplacer un document d'une collection.

Formats de fichier

Aucune route de l'API n'appelle encore cette fonction d'analyse : l'ingestion actuelle reçoit du texte déjà extrait (/rag/ingest). L'analyse des PDF et des documents Office est prévue : spec 115, tâches T-115-22 (admission des fichiers), T-115-23 (envoi), T-115-25 (branchement de l'analyse). Le crate d'extraction documentaire est en cours de livraison (T-115-31) ; il n'est pas branché sur l'API.

En attendant, l'API sait indexer un texte déjà extrait : voir « Indexer un texte » dans Routes des ressources.

Pipeline d'indexation

1. Le texte est extrait.
2. Il est découpé en morceaux. Le service de découpage intelligent propose cinq techniques, dont certaines appellent le modèle local ministral-3:3b.
3. Chaque morceau reçoit un vecteur de 384 dimensions, calculé en local par paraphrase-multilingual-MiniLM-L12-v2 (fastembed, licence Apache-2.0 ; voir Fournisseurs de modèles).
4. Les vecteurs sont rangés dans Qdrant (variables dans Variables d'environnement), dans des collections préfixées par l'identifiant de l'organisation. Ce cloisonnement est décrit dans Architecture Chatbotaurus.

Le suivi de progression en temps réel d'une ingestion n'est pas couvert par la page de détail actuelle.

Vecteurs

La liste des collections Qdrant est une vue de plateforme : elle exige une élévation d'opérateur et répond 403 sinon. La page décode un tableau alors que l'API rend un objet (engine, collections, total_vectors) : la liste ne s'affiche pas correctement. Les routes de lecture des enregistrements, de recherche et de synchronisation par collection (/vectors/<id>/...) n'existent pas dans l'API. Cette page est donc, pour un client, une page annoncée et non utilisable.

Fichiers

La page liste les fichiers de l'espace et permet d'en supprimer. L'envoi de fichiers depuis l'application, avec contrôle et chiffrement, est prévu : T-115-23 et T-115-24.

Outils

Un outil personnalisé a un nom, une couleur, une description, un schéma d'entrée (JSON Schema) et un corps de fonction. La page enregistre ces champs dans votre espace. L'exécution du corps de fonction par l'agent n'est pas couverte par ce chapitre.

Wiki LLM

Le wiki est un arbre de pages Markdown (format OKF : un fichier à en-tête type, l'identifiant est le chemin). Le serveur le lit depuis un dossier, un WebDAV ou un stockage S3. Aucun éditeur web n'est hébergé : on édite les fichiers dans le stockage. La page /wiki offre le bouton « Reindex now » et l'état de la synchronisation.

Voir aussi

• Chat : parler à un workflow déployé
• Sécurité et identifiants : les accès aux services externes et à l'API
• Routes des ressources : les routes du Document Store et des outils personnalisés
• Sauvegarde et restauration : ce qui est sauvegardé, dont les collections Qdrant
• Limites et ce que la plateforme ne fait pas : taille des fichiers et limites de l'IA ancrée
• Conseils : sessions courtes, demandes itérées, données protégées

Sécurité et identifiants

La section Sécurité gère les accès aux services externes et les accès à l'API. Elle apparaît dans le menu à partir du plan Business. Sur un plan inférieur, la limite porte sur le menu : voir la section Navigation du Tableau de bord.

Les pages

Identifiants

Un identifiant contient les informations de connexion à un service (Odoo, n8n, Matomo, un fournisseur de paiement, entre autres). La page est un catalogue de cartes rangées en 21 catégories (IA, ERP/CRM, Automatisation, Paiements EU, Données EU, Sécurité, Connecteurs, entre autres). Chaque carte a ses propres champs. Les cartes OAuth portent un choix de portées et une durée de jeton.

Comment un secret est gardé

• Il est chiffré en AES-256-GCM dans la base, avec une clé propre à chaque identifiant. La clé dérive d'une clé racine « au repos » (variable AT_REST_ENCRYPTION_KEY) distincte du secret de session quand elle est fournie. Sans elle, le secret de session sert de racine. Le détail des clés est dans Variables d'environnement.
• La valeur en clair ne revient jamais dans une réponse de l'API : la liste montre un masque.
• À la modification, la page recharge l'identifiant sans ses valeurs secrètes : chaque champ secret est remplacé par un marqueur avant d'entrer dans l'écran. Les champs secrets sont masqués, avec un bouton pour les afficher le temps de la saisie.
• Un identifiant est lié à un espace de travail. Vous ne voyez que ceux de vos espaces.

Comment un connecteur le lit

Quand un connecteur appelle un service, le serveur déchiffre l'identifiant de l'organisation qui fait la requête, et d'elle seule. Ce mécanisme est décrit dans Conception des connecteurs MCP. Au démarrage, il peut aussi publier les identifiants d'un déploiement à locataire unique comme variables d'environnement.

OpenBao

OpenBao est optionnel. Une organisation peut y garder ses secrets de connecteurs : elle enregistre un identifiant d'AppRole nommé openbaoAppRole. Le serveur lit alors ses secrets dans le coffre, avec la priorité sur ceux de la base. Sans cet identifiant, OpenBao n'est jamais contacté. La carte « OpenBao Secrets » du catalogue sert à un client qui apporte sa propre instance à un connecteur.

Variables

La page a cinq onglets : Toutes, Système, Capture, Statiques, Runtime. Les variables système sont remplies par la plateforme et ne se modifient pas. Une valeur se masque et s'affiche d'un clic. On crée et on modifie les autres. Elles se consomment dans les workflows ; les routes correspondantes sont dans Routes des ressources.

Clés API

Une clé API se crée et se gère depuis cette page ; à ce jour aucune route de l'API ne l'accepte à la place du jeton de session (l'extracteur existe dans le code, sans route consommatrice) : un appel programmatique passe par le jeton obtenu à la connexion, décrit dans Swagger. Le formulaire demande un nom et un espace de travail. La page montre la clé une seule fois à la création, puis, dans la liste, un extrait (8 premiers et 4 derniers caractères) jusqu'au rechargement de la page, et ensuite ****. Supprimer une clé la révoque. L'extracteur prévu à cet effet attend l'en-tête X-Api-Key. Voir aussi Documentation Swagger pour l'authentification de l'API.

La clé est gardée sous forme hachée. La page n'offre ni choix de portées, ni rotation automatique.

Webhooks

La page permet de créer un webhook (nom, adresse, événements parmi 12), de l'activer, de le modifier, de le supprimer et d'envoyer un test. Les 12 événements proposés : conversation démarrée ou terminée, message reçu ou envoyé, intention détectée, transfert demandé, prospect créé, workflow démarré, terminé ou échoué, appel démarré ou terminé.

Ce qui est branché, ce qui ne l'est pas :

• Envoi de test : réel. Le serveur appelle l'adresse (avec un filtre contre les adresses internes) et note la date.
• Émission automatique des événements : non branchée. Le code qui lit la table des webhooks se limite à la gestion et à l'envoi de test.
• Livraisons récentes : aucun journal de livraison n'est enregistré.
• Régénérer le secret : répond 503 FEATURE_PENDING.

En sens inverse, le serveur reçoit les notifications de fournisseurs : paiement (Mollie, PayPlag, Adyen, Stripe, Lyra, SlimPay, Wero), LiveKit, et une entrée générique. Seul Mollie sert à la facturation de la plateforme (voir Tarification) ; les autres routes de paiement existent dans le code.

Voir aussi

• Paramètres : réglages, facturation, compte et gestion des utilisateurs
• OpenBao et secrets : le coffre de secrets optionnel d'une organisation
• Workflows : où les identifiants et variables sont consommés
• Routes des ressources : variables, identifiants et outils par l'API
• Sécurité : principes, secrets et chiffrement côté exploitation
• Architecture de confiance zéro : ce que chaque requête traverse avant d'atteindre un secret

MCP et Orchestrateur

La section « Écosystème MCP » regroupe l'assistant qui construit vos workflows et les catalogues de serveurs MCP.

Les pages

Selon votre plan (voir Tarification et offres), le menu montre les trois premières pages seulement (Orchestrateur, Gateway Business, Marketplace). Les cinq autres apparaissent aux plans Enterprise et Souverain. Les anciennes adresses (/mcp-admin, /mcp-servers-business, /mcp-gateway-business) redirigent vers les adresses du tableau.

Orchestrateur

L'Orchestrateur ouvre sur deux cartes :

• « Déployer les outils de votre métier » : vous choisissez un ou plusieurs métiers, puis l'assistant prépare l'ensemble ;
• « Déployer un parcours support (pédagogique) » : un parcours pour accompagner une personne (explications, vidéos, exercices, questions).

Puis une conversation s'ouvre. Elle est portée par une session de l'API (/orchestrator/sessions). Une carte de progression montre cinq étapes :

1. Accueil
2. Secteur
3. Template
4. Validation (confirmation et identifiants)
5. Déploiement (sauvegarde, puis ouverture du chat)

Le serveur utilise des noms de phase plus fins (coaching, discovery, identification, credentials, tels qu'ils sont écrits dans le code). L'écran les ramène à ces cinq étapes.

Gateway Business

La page montre 16 métiers (détaillés dans Cas d'usage par secteur) : thérapeute, consultant, mobilier, e-commerce, formation, juridique, immobilier, médical, logistique, industrie, agriculture, créatif, association, tourisme, RH, finance. Chaque carte donne le nombre de serveurs inclus par palier. Elle ouvre la page du métier (/mcp/gateways/business/<metier>).

Gateway Projet UE

La page présente 26 catalogues de serveurs MCP pour des données publiques européennes (par exemple CORDIS, OpenAIRE, Eurostat, EPO). Les 26 sont marqués « disponibles ». Les compteurs de la page (serveurs, endpoints, opérationnels) sont calculés depuis le catalogue, pas écrits à la main. Ces sources sont décrites dans API-as-a-Service EU souverain.

Serveurs MCP Business

Cette page est un catalogue de 175 cartes de connecteurs. Elle ne décrit pas votre infrastructure. Le même catalogue, lu par l'API, est dans parcourir le catalogue de services.

• Une carte porte la mention « Déployé » seulement si le serveur figure à l'inventaire des serveurs prouvés : un outil de lecture y a rendu des données réelles. À la date du 2026-10-03, ce sont 30 serveurs sur 175. Les autres affichent « Bientôt disponible » (une seule carte affiche « Disponible » à cette date).
• Le bouton « Déployer » (info-bulle « Déployer ce serveur et ouvrir son workflow ») crée un workflow pour ce serveur et ouvre l'éditeur. Sur une carte « Bientôt disponible », il est désactivé et se lit « En préparation ».
• Vous pouvez chercher, filtrer par catégorie ou certification, et n'afficher que les serveurs déployés.

Ce qui n'est pas encore branché

Le cycle de vie des conteneurs n'est pas relié à l'API (le format des erreurs de l'API est dans Gestion des erreurs). Les appels suivants répondent 503 FEATURE_PENDING à un administrateur (un autre rôle reçoit 403) : déployer, démarrer, arrêter, redémarrer un serveur, enregistrer ses secrets, déployer un profil. La lecture du profil de sécurité répond 503 à tout rôle. L'analyse de sécurité Trivy avant déploiement n'est donc pas disponible depuis cette page. Les secrets de vos connecteurs se saisissent dans la page Sécurité et identifiants, pas par ces boutons.

Voir la référence API Catalogue Business.

Console Admin MCP

La console est prévue pour lister les services Podman (Core, MGaaS), leur santé, et pour lire leurs journaux. Elle n'est pas reliée à l'infrastructure : l'API rend une liste vide, la sonde de santé répond 503 FEATURE_PENDING, et la page affiche un bandeau qui signale que la console n'est pas câblée à l'infrastructure. Aucun chiffre n'est inventé. En attendant, un administrateur lit l'inventaire en ligne de commande avec podman ps (voir Gestion des conteneurs).

Démo Crypto

La page propose trois onglets : chiffrement homomorphe (FHE), preuve à divulgation nulle (ZKP), cryptographie post-quantique (PQC). Un bandeau « SIMULATION » le dit : la page calcule dans le navigateur, avec des entrées de démonstration. Elle ne protège aucune de vos données.

Marketplace

La page liste 93 modèles de workflow. Le bouton « Déployer » crée le workflow dans votre espace.

Voir aussi

• Workflows : l'éditeur, la palette de nœuds, les exécutions
• Sécurité et identifiants : où se saisissent les secrets de vos connecteurs
• Utiliser les connecteurs MCP : où vivent les fiches qui alimentent ces catalogues
• Routes du catalogue métier : lecture du catalogue et routes qui répondent 503
• Cas d'usage par secteur : les métiers de la Gateway Business, avec leurs connecteurs de départ
• Vue d'ensemble : ce qui est mesuré et prouvé, connecteur par connecteur

Voix et Canaux

La section Canaux décrit comment votre agent atteint vos visiteurs : apparence du widget, voix, campagnes d'appels, numéros, messageries. Les plans cités ci-dessous sont décrits dans Tarification et offres.

Les pages

/channels ouvre une page unique. Ses cinq sections ont aussi chacune leur adresse.

L'analytique des appels est une page de la section Analytique : /call-analytics. Les adresses /channels/whatsapp, /channels/telegram et /channels/sms mènent à la page Intégrations.

Marque (widget)

La page est un ensemble de huit sections repliables, suivies d'un aperçu :

1. Titre et description de l'assistant
2. Apparence et images
3. Police, thème et couleurs
4. Variantes d'interface
5. Configuration des onglets
6. Confidentialité et mentions
7. Paramètres avancés
8. Code widget et déploiement (voir aussi l'étape 7, « intégrer le chat à votre site », de la prise en main guidée)

Voix

La page a quatre onglets : reconnaissance vocale (STT), synthèse vocale (TTS), WebRTC, paramètres. Au-dessus, quatre cartes reprennent les statistiques d'appels.

Les boutons « Tester » de cette page sont désactivés. Le micro de la page Chat et de l'Orchestrateur utilise la même reconnaissance vocale.

Le code contient un pont téléphonique (LiveKit vers une ligne SIP européenne, avec une règle anti-fraude sur les destinations). Aucune page ne le pilote encore. Les variables de la chaîne vocale sont dans Variables d'environnement.

Campagnes Voice et Numéros EU

Ces deux pages sont annoncées mais non disponibles. Le bouton « Nouvelle campagne » et le bouton « Acheter un numéro » sont désactivés (« Bientôt disponible »). La page Numéros liste trois fournisseurs candidats ; elle ne gère aucun numéro.

Intégrations

La page a trois onglets : Canaux actifs, Ajouter un canal, Webhook URL. Les canaux « Via n8n » passent par le connecteur n8n.

Deux écarts à connaître :

• le formulaire de la page propose Telegram, Courriel (SMTP/IMAP), WhatsApp Business, Discord et Slack. L'API n'accepte que cinq genres : WhatsApp, Telegram, Discord, Messenger et WebRTC. Le courriel et Slack sont donc refusés à l'enregistrement, et Messenger et WebRTC n'ont pas encore de carte dans le formulaire ;
• l'état de connexion affiche « Déconnecté » pour tous les canaux : aucune sonde de connexion n'existe, et la page ne montre pas un « Connecté » qu'elle ne peut pas mesurer.

Analytique des appels

La page /call-analytics liste les appels (30 derniers jours) et ouvre le détail d'un appel (transcription, coût, latence). Le service de statistiques d'appels rend le nombre d'appels, les appels terminés ou abandonnés et la durée moyenne. Les champs avancés (temps de réponse, sentiment, heures de pointe, intentions) sont renvoyés vides, faute de données stockées : la page n'invente pas de taux de résolution ni de satisfaction.

Voir aussi

• Analytique : la page des appels et les autres mesures d'usage
• Sécurité et identifiants : les accès aux services externes et à l'API
• Chat : le micro du chat utilise la même reconnaissance vocale
• Déploiement avec Podman : les services de voix font partie du plan backend
• Connecteur n8n : le relais des canaux WhatsApp, Discord et Messenger
• Limites et ce que la plateforme ne fait pas : les langues de la voix et les minutes par offre

Analytique

Les pages d'analytique et d'évaluation mesurent l'usage de votre agent et la qualité de ses réponses. Certaines mesures sont encore partielles : ce chapitre dit lesquelles.

Les pages

Les plans Essentiel et Starter ont l'analytique simple : deux pages (Analytique et Historique Chat). Les plans sont décrits dans Tarification et offres.

Analytique 360

La page offre une période (24 heures, 7, 30 ou 90 jours), un filtre de canal (Tous, Web, WhatsApp, Telegram, Voix ; voir Voix et Canaux) et quinze onglets. Le filtre de canal n'est pas transmis à l'API : il ne change aucun chiffre aujourd'hui.

Un seul onglet est branché : Vue d'ensemble. Les quatorze autres affichent « Section en cours de portage V1 » (Interactions, Performance, Outils MCP, Gateways, Ollama / LLM, Voix, Base de connaissances, Workflows, Infrastructure, Sécurité / Crypto, Protocole MCP, Leads / CRM, Conformité EU, Anti-Hallucination).

Dans la Vue d'ensemble :

Les graphiques (conversations par jour, messages par heure, répartition par canal) n'ont pas encore de données et s'affichent vides. Le bouton d'export est désactivé. Un zéro ou un tiret sur cette page ne signifie donc pas « rien ne s'est passé » : cela peut signifier « non mesuré ».

Les cibles affichées (résolution, temps de réponse, abandon, hallucination) sont des objectifs de la page, pas des résultats mesurés.

Leads / CRM

La page suit les prospects de votre espace :

• liste avec recherche et filtre de statut, ou tableau en colonnes (nouveau, contacté, qualifié, proposition, négociation) ;
• création, modification, suppression d'un prospect ;
• quatre compteurs de synthèse ;
• une liste des prospects venus des formulaires publics du site (contact, lettre d'information).

La page ne crée pas de prospect à partir de l'Orchestrateur.

Lead Funnel

La page affiche cinq paliers de score (Cold, Engaged, Qualified, Hot, Highly Qualified). Les compteurs y sont à zéro : la page est une base d'éditeur, pas encore une mesure.

Journaux

• Logs App (/logs) : les 50 derniers événements du serveur, lus en mémoire. L'historique long via VictoriaLogs est annoncé pour plus tard (voir Journaux pour les journaux côté serveur).
• Logs Serveur (/server-logs) : filtre par niveau et par recherche sur les dernières 24 heures, pause, effacement, export, rafraîchissement.

Conformité EU

La page affiche une matrice par référentiel : RGPD, NIS2, EUCS, Gaia-X, eIDAS, avec un score, des vérifications réussies, en alerte ou en échec, et un filtre. Le rapport vient de l'API (/compliance/report). Ce rapport est une auto-évaluation déclarative, pas un audit indépendant ; chaque vérification porte sa base (« self-declared » ou « measured »). Si l'API ne répond pas, la page affiche un rapport local fixe à la place.

Voir le chapitre Conformité RGPD.

Évaluations

Réservées aux plans Enterprise et Souverain.

1. Datasets : importez un fichier CSV de questions et de réponses attendues.
2. Évaluateurs : créez un évaluateur de l'un de ces types : personnalisé, juge LLM, similarité, expression régulière.
3. Évaluations : lancez une évaluation en choisissant un workflow, un dataset et un ou plusieurs évaluateurs. Le détail d'une évaluation a sa page (/evaluations/<id>).
4. A/B Testing : comparez des variantes de prompt.

Les mesures de précision, de rappel ou de F1 ne figurent pas parmi les types d'évaluateur.

Voir aussi

• Voix et Canaux : apparence du widget, voix, campagnes d'appels, numéros, messageries
• Workflows : l'éditeur, la palette de nœuds, les exécutions
• Chat : l'historique et les messages proactifs vus depuis la page Chat
• Supervision : les métriques et points de santé côté exploitation
• Journaux : où le backend écrit, et l'export vers VictoriaLogs
• Conformité RGPD : le fond du référentiel que la matrice auto-évalue

Paramètres

Ce chapitre couvre la section Paramètres (réglages, facturation, compte) et la section Gestion (utilisateurs, rôles, SSO, connexions). Les espaces de travail vivent dans la section Agence. Les plans minimums du tableau sont ceux de Tarification et offres.

Les pages

La page des tarifs (/pricing) est une page publique du site, pas une page de l'application. Pour gérer votre abonnement, utilisez Facturation.

Paramètres

La page a trois onglets : Général, Fonctionnalités, Accès rapides.

• Général : six champs (nom du site, adresse du site, courriel de support, taille maximale de fichier, délai de session, langue par défaut).
• Fonctionnalités : neuf interrupteurs (réponses en flux continu, envoi de fichiers, entrée vocale, tableau de bord analytique, interface générative, multi-locataire, SSO, journaux d'audit, limitation de débit).
• Accès rapides : huit raccourcis vers d'autres pages (apparence, sécurité, clés API, entre autres).

Limite actuelle : le bouton Enregistrer envoie les six champs et les neuf interrupteurs sous les clés generalSettings et featureFlags. L'API de cette page ne lit que timezone et language, que la page n'envoie pas : rien n'est enregistré depuis cette page. Le fuseau horaire et la langue de l'utilisateur se règlent dans Compte, qui les enregistre.

Compte

La page porte le profil, le mot de passe, la double authentification, les notifications, l'export de vos données et la suppression du compte (voir Conformité RGPD pour l'exercice des droits). Les langues proposées sont le français, l'anglais, le néerlandais et l'allemand. Seuls le français et l'anglais ont une interface complète (1 610 clés au 2026-10-03) : le néerlandais et l'allemand n'ont que 26 clés traduites, le reste s'affiche en français.

Double authentification

Après le mot de passe, la connexion demande un second facteur : un code envoyé par courriel, ou le code d'une application d'authentification (TOTP) si vous l'avez activée dans Compte. L'administrateur du déploiement peut exiger le TOTP pour tous les comptes, ou pour des rôles choisis. Cette exigence est une option de configuration du serveur, pas une règle fixe par rôle (voir Variables d'environnement).

Utilisateurs et rôles

La page Utilisateurs liste les comptes de votre organisation, avec leur état, et permet de les modifier. Le bouton « Ajouter un utilisateur » crée un compte à partir d'un courriel, d'un nom, d'un rôle et d'un statut. La page Rôles liste les rôles de votre organisation, en crée et en supprime.

Les rôles ne sont pas une liste fixe : chaque organisation définit les siens. Le moteur de politiques est décrit dans Architecture de confiance zéro. Une permission s'écrit ressource:action (par exemple credentials:view). Le catalogue compte 88 permissions en 18 catégories, parmi lesquelles mcpgateways, mcpgatewayflows, tools, credentials, variables, apikeys, documentStores, datasets, executions, evaluators, evaluations, workspace, logs. Le joker * donne tous les droits. Il n'existe pas de permission workflows:view : les workflows relèvent de mcpgateways et mcpgatewayflows.

Les pages d'administration /admin* sont réservées aux rôles admin, superadmin, super_admin et owner. Tout autre rôle, ou un rôle inconnu, voit un écran « accès réservé ».

Espaces de travail

Un espace de travail regroupe des workflows, identifiants et historiques. La page /workspaces liste, crée et modifie les espaces de votre organisation. Les données sont cloisonnées par organisation (voir Architecture Chatbotaurus). OpenBao n'intervient que si votre organisation a choisi cette option (voir Sécurité et identifiants).

SSO

La page Config SSO a trois onglets : configuration, fournisseurs, sessions. La configuration Authentik demande un identifiant court (slug), un identifiant client et l'adresse du serveur d'authentification. Deux interrupteurs activent le SSO et la création automatique des utilisateurs. L'onglet sessions permet de terminer une session. Le bouton « Ajouter un provider » (SAML, LDAP) est désactivé : l'ajout de fournisseurs supplémentaires est en cours d'intégration côté serveur.

Voir le guide SSO Authentik.

Activité de connexion

Le tableau liste, pour chaque connexion : l'utilisateur, le statut, l'adresse IP, la localisation, l'appareil et l'heure. Il offre des filtres de recherche, de statut et de dates, une alerte quand des connexions suspectes sont détectées, et un export CSV. Les limiteurs de connexion sont décrits dans Sécurité.

Voir aussi

• Tableau de bord : la première page après la connexion
• Sécurité et identifiants : les accès aux services externes et à l'API
• SSO Authentik : la configuration côté serveur du bouton de connexion unique
• Tarification et offres : la facturation, l'engagement et les moyens de paiement
• Conformité RGPD : export et suppression des données, les droits exercés depuis Compte
• Prise en main guidée : créer le compte et inviter l'équipe

Conseils

Une page de conseils courts, tous vérifiables dans le produit ou dans le code.

Parlez en langage naturel

Il n'y a pas de syntaxe spéciale. Décrivez la tâche comme à un collègue : Chatbotaurus choisit l'outil du connecteur qui y répond. Plus la demande nomme l'objet (un client, une facture, un rendez-vous), plus le choix de l'outil est sûr.

Étendez avec des connecteurs

Chatbotaurus parle le protocole MCP. Chaque service métier est un connecteur décrit par un fichier connectors/<id>.yaml. Le dépôt en contient 195 (mesure du 2026-10-03 : ls connectors/*.yaml | wc -l). Le chapitre Vue d'ensemble des connecteurs présente le catalogue. Pour en écrire un, voir Fichiers de configuration.

Les modèles tournent chez vous

L'inférence passe par Ollama, sur votre infrastructure. La liste des modèles retenus est fixée dans crates/forge-core/src/model_governance.rs :

Changer cette liste est une décision de souveraineté, pas un réglage : elle se modifie avec une justification de licence. Le modèle de génération se choisit avec OLLAMA_MODEL et le modèle d'embeddings du pipeline RAG avec EMBEDDING_MODEL (voir Variables d'environnement).

Gardez les sessions courtes

Une conversation longue remplit la fenêtre de contexte du modèle, et les réponses perdent en précision. Si elles deviennent moins pertinentes, ouvrez une nouvelle conversation. C'est un conseil d'usage, pas une mesure de ce dépôt.

Itérez sur vos demandes

Vous n'avez pas à trouver la bonne formulation du premier coup. Reformulez, précisez l'objet, relancez.

Profils du catalogue

Le catalogue regroupe ses serveurs en quatre profils :

GET /api/v1/mcp/catalog-business/profiles les liste. La route POST /api/v1/mcp/catalog-business/profiles/{name}/deploy existe, mais elle répond aujourd'hui 503 FEATURE_PENDING : le pilotage de Podman par le backend n'est pas branché, elle ne déploie rien. Le tutoriel Parcourir le catalogue de services et préparer un déploiement explique ce qui marche et ce qui est en sommeil.

Protégez vos données

• Les points d'accès de la voix doivent être dans l'UE : le code refuse les autres (validate_eu_endpoint, crates/forge-voice/src/stt.rs).
• Le registre des connecteurs rejette un connecteur dont les données ne restent pas dans l'UE ou chez vous.
• Aucun secret n'est stocké dans les manifestes de connecteurs : ils lisent l'environnement.
• Les journaux masquent clés, jetons et adresses e-mail avant écriture.

Détails et limites : Sécurité.

Surveillez

Sondez GET /api/v1/readyz depuis votre supervision. Le chapitre Supervision dit ce qui est mesuré aujourd'hui et ce qui ne l'est pas encore.

Mettez à jour avec méthode

Si vous disposez des sources sous licence : récupérez les changements, puis reconstruisez le workspace.

git pull
cargo build --workspace --release

En développement, dx serve (lancé depuis crates/forge-ui) recharge le frontend à chaque modification. Le backend se redémarre.

Voir aussi

• Variables d'environnement — régler le modèle, les embeddings et les points d'accès vocaux
• Fichiers de configuration — écrire ou corriger le manifeste YAML d'un connecteur
• Contribuer — construire, vérifier et livrer si vous disposez des sources
• Questions fréquentes — réponses courtes aux questions générales, techniques et de positionnement
• Glossaire — définitions des termes techniques employés dans ces conseils

Connecteurs MCP

Un connecteur est un fichier YAML du dossier connectors/ du dépôt. Il déclare un service, sa méthode d'authentification, sa licence et la liste des outils que l'agent peut appeler. Ce chapitre donne les chiffres mesurés le 2026-10-03 et renvoie vers les douze connecteurs décrits dans ce livre.

Ce qui est mesuré

Les trois premiers chiffres sont aussi ceux du site public. Ils viennent de crates/forge-ui/src/config/chiffres_mesures.rs, fichier généré, daté du 2026-10-03.

Le nombre de fichiers (195) et le nombre d'entrées du catalogue (108) ne se recouvrent pas. Douze entrées du catalogue n'ont pas de fiche YAML : collabora, faster-whisper, gnuhealth, logseq, mywms, openmom, pgadmin, postgresql, property-base, timescaledb, valkey et une entrée de détection d'intrusion. À l'inverse, 99 fichiers YAML n'ont pas d'entrée au catalogue (gabarit compris).

Un connecteur du catalogue au statut coming-soon est annoncé, pas ouvert. Le statut est une donnée du catalogue, il ne dit rien de l'état du fichier YAML.

Comment un connecteur est chargé

Au démarrage, forge-api lit le dossier connectors/, remplace les variables ${VAR:-défaut} par l'environnement, puis enregistre un connecteur par fichier. Le moteur HTTP sert les fichiers à authentification HTTP. Le connecteur odoo a son propre client XML-RPC. Le connecteur calrs passe par une commande dans un conteneur (voir CalRS). Source : connectors/README.md et crates/forge-mcp/src/connector/catalogue.rs.

Dans tools/list, le nom d'un outil des connecteurs HTTP est préfixé par l'identifiant du connecteur : l'outil get_visits du fichier matomo.yaml s'appelle matomo.get_visits (moteur HTTP des connecteurs). Les chapitres suivants donnent les noms tels qu'ils sont écrits dans les fichiers, sans ce préfixe.

Chaque connecteur déclare sa conformité. Le registre le refuse si gdpr_compliant vaut false ou si data_residency n'appartient pas à la liste eu, eu-west, eu-central, france, germany, finland, netherlands, ireland, self-hosted (connectors/README.md, section « Gate EU / Gaia-X »). Cette règle porte sur ce que le fichier déclare. Elle ne prouve pas où tourne l'instance du client.

Une seconde règle décide du dispatch : seuls les identifiants de la liste ALLOWED_MCP_SERVERS (liste des serveurs autorisés du code) sont exécutés, et tools/list n'affiche que leurs outils. Mesuré le 2026-10-03 : sur les 194 fichiers hors gabarit, 98 sont dans cette liste et 96 n'y sont pas. dolibarr et freescout font partie des 96 (un test du dépôt le verrouille) : leur fiche se charge, leurs outils ne sont pas appelables tant que l'identifiant n'est pas ajouté à la liste.

Authentification

Types d'authentification présents dans les 195 fichiers, mesurés le 2026-10-03 : aucune (73), bearer (52), clé d'API en en-tête (33), basic (20), jeton de connexion (5), jeton en paramètre d'URL (4), oauth2 (3), et quelques cas particuliers. Deux fichiers (odoo, calrs) n'ont pas de bloc auth parce que leur transport n'est pas HTTP.

Les chapitres suivants nomment les variables que chaque fichier lit. Côté locataire, les valeurs sont saisies comme identifiants de la plateforme et stockées chiffrées en base. OpenBao est un mode optionnel : une organisation qui y a enregistré son AppRole voit ses secrets lus depuis OpenBao en priorité. Sans cet AppRole, OpenBao n'est jamais contacté (résolution des identifiants du code).

Les douze connecteurs décrits ici

Compte d'outils mesuré dans chaque YAML le 2026-10-03. Pour odoo, le YAML ne déclare que 6 outils ; les 711 outils nommés vivent dans le registre Rust.

« Lecture seule » veut dire que tous les outils du YAML utilisent la méthode GET. « Service dans le plan client » veut dire qu'un container_name: mcp-… existe dans podman-compose.vps2.yml. Une réponse « non » ne dit pas que le service est inutilisable : le client peut apporter sa propre instance. « Autorisé au dispatch » veut dire que l'identifiant figure dans ALLOWED_MCP_SERVERS.

Les outils d'écriture sont classés par leur nom (classification de sécurité des outils, dans le code). Un nom qui porte drop, truncate, erase, purge, wipe, ou qui se termine par unlink ou destroy, n'est jamais exécuté par l'agent. Un nom qui porte delete, cancel, refund, pay, charge, transfer, remove ou revoke n'est exécuté qu'après une autorisation humaine explicite. Les outils create, update et send passent sans cette étape. Les chapitres qui suivent écrivent « supprime » pour ce que le fichier déclare ; ce que l'agent exécute seul est plus étroit.

Le catalogue métier

Le catalogue est servi par l'API sous /api/v1/mcp/catalog-business, pour un utilisateur authentifié. GET /api/v1/mcp/catalog-business renvoie les 108 entrées embarquées dans le binaire, avec un filtre optionnel par catégorie. GET /api/v1/mcp/catalog-business/{id}/registry-tools liste les outils que le registre connaît pour un connecteur. Les routes de cycle de vie (déployer, démarrer, arrêter, secrets) répondent encore 503 avec le marqueur feature_pending : l'adaptateur Podman n'est pas branché (crates/forge-api/src/routes/mcp_catalog_business.rs, commentaire de tête).

Les entrées sont rangées en 34 catégories. Par taille décroissante, au 2026-10-03 : Communication (7 entrées), puis CRM & ERP, DevOps, Monitoring et Database (5 entrées chacune).

Les connecteurs de données publiques de l'UE

Dix-huit fichiers portent un nom de secteur : agriculture, culture, cybersecurity, education, employment, energy, environment, fintech, foodsafety, governance, innovation, industry, legaltech, maritime, sme, health, spatial, quantum. Chacun interroge le portail de données ouvertes de l'UE, sans authentification, avec 28 à 30 outils. Un dix-neuvième, broadcast, est un connecteur à jeton avec 2 outils.

Utiliser un connecteur

1. Vérifiez dans le tableau ci-dessus que la colonne « Autorisé au dispatch » vaut « oui » : sinon les outils ne sont pas appelables.
2. Ayez une instance du service : la vôtre, ou celle du plan client si la colonne « Service dans le plan client » vaut « oui ».
3. Enregistrez les identifiants : page Identifiants (/credentials) de l'application, fiche du connecteur. Le chapitre du connecteur donne le nom de la fiche et ses champs (CalRS n'a rien à saisir). Connecter Odoo à la passerelle MCP déroule ce parcours de bout en bout.
4. Posez la question dans le chat, ou appelez l'outil par tools/call (Routes MCP).

Ajouter un connecteur

Le tutoriel Créer votre premier connecteur MCP décrit la forme d'un fichier YAML.

Voir aussi

• Conception des connecteurs MCP : deux types de connecteurs, contrôle de conformité UE et cycle de vie
• Routes MCP : ouvrir une session et appeler un outil par JSON-RPC
• Routes du catalogue métier : routes du catalogue métier, lecture opérationnelle et cycle de vie prévu
• Utiliser les connecteurs MCP : fiches de connecteurs présentes et consultation du catalogue par l'API
• Tarification : nombre de connecteurs métier inclus dans chaque offre

Connecteur Authentik

Authentik est un fournisseur d'identité (SSO, OIDC, SAML, LDAP). Le connecteur lit l'API REST v3 d'une instance Authentik. Il est en lecture seule : aucun de ses outils ne crée, ne modifie ni ne supprime quoi que ce soit.

Mesuré le 2026-10-03 dans connectors/authentik.yaml : 442 outils, tous en méthode GET.

Ce que déclare le fichier

Outils

Les noms d'outils sont de la forme authentik_<ressource>_<action>. Exemples réels : authentik_users_list, authentik_users_get, authentik_groups_list, authentik_applications_list, authentik_applications_check_access.

Répartition par préfixe de nom, mesurée sur les 442 outils :

Les 8 autres outils se répartissent entre users et groups (2 chacun) et quatre ressources isolées (brands, root, schema, property, 1 chacune).

Les ressources users et groups n'ont chacune que deux outils : lister et lire. Il n'existe pas d'outil authentik_create_user ou authentik_delete_user.

Configuration

Les valeurs se saisissent comme identifiants de la plateforme : page Identifiants (/credentials), fiche Authentik IAM, champs « URL du serveur » et « API Token » (ce dernier alimente AUTHENTIK_API_KEY). Le délai d'attente déclaré par le fichier est de 30 000 ms.

Déploiement

Le fichier compose du plan backend (podman-compose.yml) déploie un service Authentik pour l'authentification de la plateforme. Le fichier du plan client (podman-compose.vps2.yml) ne contient aucun service Authentik. Le connecteur ne dépend pas de ce service : il vise l'instance désignée par AUTHENTIK_URL.

Cas d'usage

• Lister les utilisateurs, groupes et applications d'une instance.
• Vérifier l'accès d'un utilisateur à une application (authentik_applications_check_access).
• Consulter les flux, fournisseurs, politiques et événements pour un audit.

Limites

• Lecture seule. Le provisionnement d'utilisateurs n'est pas fait par ce connecteur.
• Le statut du connecteur au catalogue est available. Cela décrit l'entrée du catalogue, pas une preuve de service sur votre instance.

Fichier source

Le connecteur est déclaré dans connectors/authentik.yaml.

Voir aussi

• Vue d'ensemble : chiffres mesurés, chargement et règles communes aux douze connecteurs
• Créer votre premier connecteur MCP : forme d'un fichier YAML et ajout d'un connecteur à la passerelle
• Routes MCP : ouvrir une session et appeler un outil par JSON-RPC
• Tarification : nombre de connecteurs métier inclus dans chaque offre
• SSO Authentik : le même produit, utilisé pour la connexion à la plateforme

Connecteur CalRS

CalRS est un outil de prise de rendez-vous écrit en Rust, sous licence AGPL-3.0, avec une base SQLite et le protocole CalDAV. Il est le seul connecteur d'agenda de ce type dans connectors/ : connectors/calrs.yaml (décision notée dans l'en-tête de ce fichier, ADR-0009).

Ce chapitre garde le nom de fichier calcom.md pour que les liens existants continuent de fonctionner.

Transport

CalRS n'expose pas d'API HTTP, selon l'en-tête de connectors/calrs.yaml. Le connecteur ne parle donc pas à une adresse web. Il lance une commande podman exec … calrs <sous-commande> dans le conteneur CalRS. Conséquences :

• il n'y a ni adresse d'instance, ni clé d'API, ni en-tête d'authentification à configurer ;
• l'autorisation est celle du socket Podman, en amont du connecteur ;
• aucune variable d'environnement n'est lue par ce connecteur.

Le nom d'identifiant historique calcomApi existe encore côté plateforme. Il est rattaché au connecteur calrs et ne publie aucune variable d'environnement (table de correspondance des identifiants du code, entrée calcomApi).

Outils

Mesuré le 2026-10-03 : 7 outils déclarés dans connectors/calrs.yaml. Le client Rust qui les exécute est crates/forge-mcp/src/connector/calrs_cli_client.rs.

Trois de ces outils écrivent : create_booking, cancel_booking, create_event_type.

Déploiement

Un service CalRS figure dans podman-compose.vps2.yml, avec une image construite localement et un volume de données. Un commentaire de ce fichier le classe « catalogue » et précise qu'il est hors des plans thérapeute depuis le 2026-07-08.

Le connecteur n'a de sens que si le conteneur CalRS tourne sur la même machine que le processus qui lance la commande.

Limites

• Aucun outil de disponibilité par utilisateur : list_slots travaille sur un type de rendez-vous identifié par son slug.
• Le conteneur déployé ne contient aucun type de rendez-vous par défaut. Il faut en créer un (create_event_type) avant de lister des créneaux. Cette remarque vient d'une mesure du 2026-08-30 consignée dans le YAML.
• L'entrée du catalogue métier (calrs, catégorie Scheduling) a le statut available.

Fichiers sources

Le connecteur est déclaré dans connectors/calrs.yaml et exécuté par crates/forge-mcp/src/connector/calrs_cli_client.rs.

Voir aussi

• Vue d'ensemble : chiffres mesurés, chargement et règles communes aux douze connecteurs
• Créer votre premier connecteur MCP : forme d'un fichier YAML et ajout d'un connecteur à la passerelle
• Routes MCP : ouvrir une session et appeler un outil par JSON-RPC
• Tarification : nombre de connecteurs métier inclus dans chaque offre
• Déploiement Podman : plan client, réseaux et unités où tourne le conteneur CalRS

Connecteur Dolibarr

Dolibarr est un ERP/CRM open source pour petites structures. Le connecteur lit l'API REST de Dolibarr. Il est en lecture seule : il n'existe aucun outil de création, de modification ni de suppression.

Mesuré le 2026-10-03 dans connectors/dolibarr.yaml : 263 outils, tous en méthode GET (156 de type liste, 107 de type lecture d'un enregistrement).

Ce connecteur n'est pas appelable aujourd'hui : son identifiant ne figure pas dans la liste des serveurs autorisés (section Déploiement plus bas). Vous pouvez enregistrer ses identifiants, mais tools/list n'affiche pas ses outils et un appel est refusé.

Ce que déclare le fichier

Le fichier indique que les outils ont été vérifiés contre la documentation officielle de l'API REST de Dolibarr (consultée le 2026-06-24) et que les écritures (POST, PUT) sont exclues par choix.

Outils

Les noms suivent deux formes : list_<ressource> et get_<ressource>…. Exemples réels : list_thirdparties, get_thirdparty, list_invoices, get_invoice, list_proposals, list_orders, list_products, list_bankaccounts.

Ressources les mieux couvertes, par nombre d'outils dont un segment du nom (séparé par _) est la ressource, mesuré sur les 263 outils :

Le reste couvre des ressources plus petites : contrats, interventions, tickets, notes de frais, salaires, entrepôts, mouvements de stock, factures fournisseurs.

Configuration

Dans l'application : page Identifiants (/credentials), fiche Dolibarr, champs « URL du serveur » et « API Key ».

Déploiement

Ni podman-compose.vps2.yml ni podman-compose.yml ne déploient Dolibarr. Le connecteur vise une instance que vous fournissez. L'entrée du catalogue métier a le statut coming-soon.

L'identifiant dolibarr ne figure pas dans ALLOWED_MCP_SERVERS (liste des serveurs autorisés du code). Le fichier se charge, mais ses outils n'apparaissent pas dans tools/list et le dispatch les refuse (un test du dépôt le verrouille).

Limites

• Lecture seule. Créer un devis ou une facture n'est pas possible avec ce connecteur.
• Quatre outils portent le préfixe dolibarr_ (par exemple dolibarr_get_mos, dolibarr_list_users_groups), les 259 autres non : le nommage n'est pas uniforme.

Fichier source

Le connecteur est déclaré dans connectors/dolibarr.yaml.

Voir aussi

• Vue d'ensemble : chiffres mesurés, chargement et règles communes aux douze connecteurs
• Créer votre premier connecteur MCP : forme d'un fichier YAML et ajout d'un connecteur à la passerelle
• Routes MCP : ouvrir une session et appeler un outil par JSON-RPC
• Tarification : nombre de connecteurs métier inclus dans chaque offre
• Odoo : l'autre ERP/CRM du livre, avec des outils d'écriture

Connecteur Forgejo

Forgejo est une forge logicielle auto-hébergeable (dépôts Git, tickets, demandes de fusion, versions). Le connecteur appelle son API REST v1, compatible Gitea.

Mesuré le 2026-10-03 dans connectors/forgejo.yaml : 482 outils.

Le connecteur lit donc 248 ressources et en modifie 234. Il peut supprimer des dépôts, des branches, des versions et des webhooks.

Ce que déclare le fichier

Outils

Les noms n'ont pas de préfixe de connecteur : repos_list, repos_create, issues_create, pulls_merge, branches_protect, releases_create, webhooks_create.

Répartition par préfixe de nom, mesurée sur les 482 outils (les préfixes repos et repo sont deux familles distinctes dans le fichier) :

Les préfixes restants (get, list, releases, activitypub, webhooks, labels, milestones, tags, packages, notify, settings, commits, notifications, markdown, et quelques autres) totalisent 80 outils.

Opérations couvertes par des outils nommés : création, lecture, modification et suppression de dépôts ; tickets avec commentaires, étiquettes et assignations ; demandes de fusion avec diff, revues et fusion ; branches avec protection ; versions ; webhooks ; étiquettes et jalons ; organisations et équipes ; paquets ; administration.

Configuration

Dans l'application : page Identifiants (/credentials), fiche Forgejo Git, champs « URL du serveur » et « Access Token » (ce dernier alimente FORGEJO_API_KEY).

Le délai d'attente déclaré est de 30 000 ms.

Déploiement

podman-compose.vps2.yml contient un service Forgejo (image officielle épinglée, base SQLite, ports liés à la boucle locale). Un commentaire de ce fichier précise qu'il est conservé pour la pile de développement du poste, et qu'il ne fait plus partie du plan client déployé depuis le 2026-09-10. Pour un usage client, le connecteur vise l'instance désignée par FORGEJO_URL.

L'entrée du catalogue métier a le statut coming-soon.

Limites

• La licence MIT est celle que déclare le fichier YAML. Vérifiez la licence de la version de Forgejo que vous installez.
• Les outils de lecture et d'écriture sont dans le même connecteur : les droits réels dépendent du jeton fourni.

Fichier source

Le connecteur est déclaré dans connectors/forgejo.yaml.

Voir aussi

• Vue d'ensemble : chiffres mesurés, chargement et règles communes aux douze connecteurs
• Créer votre premier connecteur MCP : forme d'un fichier YAML et ajout d'un connecteur à la passerelle
• Routes MCP : ouvrir une session et appeler un outil par JSON-RPC
• Tarification : nombre de connecteurs métier inclus dans chaque offre
• Migration depuis d'autres outils : équivalents européens des services hors UE, forge logicielle comprise

Connecteur FreeScout

FreeScout est un outil de support client auto-hébergeable, sous licence AGPL-3.0. Le connecteur lit les conversations, clients et boîtes de réception via l'API REST de FreeScout. Il est en lecture seule.

Mesuré le 2026-10-03 dans connectors/freescout.yaml : 15 outils, tous en méthode GET.

Ce connecteur n'est pas appelable aujourd'hui : son identifiant ne figure pas dans la liste des serveurs autorisés (section Déploiement plus bas). Vous pouvez enregistrer ses identifiants, mais tools/list n'affiche pas ses outils et un appel est refusé.

Ce que déclare le fichier

Le statut a_verifier est celui que porte le fichier. Dans le dépôt, il signifie qu'aucune sonde n'a encore établi qu'un amont répond (référentiel de statut amont du dépôt). Les outils sont donc vérifiés contre le contrat déclaré de l'API, pas contre une réponse réelle.

Outils

Le fichier précise que les 14 opérations d'écriture de l'API FreeScout ont été laissées de côté sur décision du titulaire, le 2026-09-04. Répondre à un ticket, changer un statut ou assigner une conversation n'est donc pas possible avec ce connecteur.

Configuration

Dans l'application : page Identifiants (/credentials), fiche FreeScout Helpdesk, champs « URL du serveur » et « API Key ».

Déploiement

Ni podman-compose.vps2.yml ni podman-compose.yml ne déploient FreeScout. Le connecteur vise une instance que vous fournissez. L'entrée du catalogue métier a le statut coming-soon.

L'identifiant freescout ne figure pas dans ALLOWED_MCP_SERVERS (liste des serveurs autorisés du code). Le fichier se charge, mais ses outils n'apparaissent pas dans tools/list et le dispatch les refuse (un test du dépôt le verrouille).

Cas d'usage

• Retrouver une conversation ou un client par l'agent.
• Consulter les temps passés et les rapports.

Fichier source

Le connecteur est déclaré dans connectors/freescout.yaml.

Voir aussi

• Vue d'ensemble : chiffres mesurés, chargement et règles communes aux douze connecteurs
• Créer votre premier connecteur MCP : forme d'un fichier YAML et ajout d'un connecteur à la passerelle
• Routes MCP : ouvrir une session et appeler un outil par JSON-RPC
• Tarification : nombre de connecteurs métier inclus dans chaque offre
• Utiliser les connecteurs MCP : fiches de connecteurs présentes et consultation du catalogue par l'API

Connecteur Listmonk

Listmonk est un gestionnaire de lettres d'information et de listes de diffusion, sous licence AGPL-3.0. Le connecteur appelle son API REST.

Mesuré le 2026-10-03 dans connectors/listmonk.yaml : 76 outils.

Ce que déclare le fichier

Outils

La plupart des outils portent le préfixe listmonk_. 17 outils n'en ont pas, par exemple get_bounces ou get_campaign_analytics.

Il n'existe pas d'outil d'annulation de campagne nommé comme tel : les outils de pilotage d'une campagne sont listmonk_start_campaign et listmonk_pause_campaign.

Des outils de suppression en masse existent (listmonk_subscribers_query_delete_create, listmonk_maintenance_subscribers_delete). Ils agissent sur des abonnés réels.

Configuration

Dans l'application : page Identifiants (/credentials), fiche Listmonk Newsletter, champs « URL du serveur », « Username » (qui alimente LISTMONK_API_USER) et « API Token » (qui alimente LISTMONK_API_KEY).

Les variables LISTMONK_USERNAME et LISTMONK_PASSWORD ne sont lues par aucun connecteur.

Déploiement

podman-compose.vps2.yml déploie un service Listmonk (image officielle, base Postgres partagée, volume pour les médias téléversés). L'entrée du catalogue métier a le statut coming-soon.

Fichier source

Le connecteur est déclaré dans connectors/listmonk.yaml.

Voir aussi

• Vue d'ensemble : chiffres mesurés, chargement et règles communes aux douze connecteurs
• Créer votre premier connecteur MCP : forme d'un fichier YAML et ajout d'un connecteur à la passerelle
• Routes MCP : ouvrir une session et appeler un outil par JSON-RPC
• Tarification : nombre de connecteurs métier inclus dans chaque offre
• Migration depuis d'autres outils : Listmonk parmi les remplaçants d'un service de courriel marketing hors UE

Connecteur Matomo

Matomo est un outil d'analyse d'audience web, sous licence GPL-3.0, que l'on peut héberger soi-même. Le connecteur interroge son API de rapports. Il est en lecture seule.

Mesuré le 2026-10-03 dans connectors/matomo.yaml : 113 outils, tous en méthode GET.

Pourquoi seulement de la lecture

L'API de Matomo modifie des données par des requêtes GET. Une passe de correction du 2026-06-25, consignée dans le fichier, a donc retiré 29 outils de mutation (création et modification d'objectifs, de sites, d'utilisateurs, de segments, d'alertes, anonymisation, suppression de données de personnes). Il reste 113 méthodes de rapport. generate_report et export_data_subjects sont conservés : ils renvoient des données.

Ce que déclare le fichier

Le jeton voyage dans l'URL de la requête, parce que Matomo n'accepte pas d'en-tête d'authentification pour cette API (explication consignée dans le fichier). Gardez-le hors de tout journal d'accès que vous ne maîtrisez pas.

Outils

Les noms n'ont pas de préfixe de connecteur. Chaque outil prend en paramètres idSite (entier), period et date. Il n'existe pas de variable MATOMO_SITE_ID : le site se choisit à chaque appel.

Exemples réels :

Il n'existe pas d'outil nommé get_live_visitors. Les visites récentes se lisent avec get_last_visits_details.

Configuration

Dans l'application : page Identifiants (/credentials), fiche Matomo Analytics, champs « URL du serveur », « Site ID » et « API Token » (ce dernier alimente MATOMO_API_KEY). Le champ « Site ID » est demandé par le formulaire, mais le connecteur ne le lit pas : indiquez le site (idSite) à chaque appel.

Les variables MATOMO_TOKEN et MATOMO_SITE_ID ne sont lues par aucun connecteur.

Déploiement

podman-compose.vps2.yml déploie Matomo (image officielle épinglée) avec une base MariaDB dédiée. L'entrée du catalogue métier a le statut available.

Exemple

Combien de visiteurs uniques sur le site 1 la semaine dernière ?

L'agent choisit get_unique_visitors avec idSite, period et date.

Fichier source

Le connecteur est déclaré dans connectors/matomo.yaml.

Voir aussi

• Vue d'ensemble : chiffres mesurés, chargement et règles communes aux douze connecteurs
• Créer votre premier connecteur MCP : forme d'un fichier YAML et ajout d'un connecteur à la passerelle
• Routes MCP : ouvrir une session et appeler un outil par JSON-RPC
• Tarification : nombre de connecteurs métier inclus dans chaque offre
• RGPD : droits des personnes, en regard de l'outil d'export des données

Connecteur n8n

n8n est un outil d'automatisation de workflows. Le connecteur appelle l'API publique REST de n8n pour lister, créer, activer et supprimer des workflows, et pour lire les exécutions.

Mesuré le 2026-10-03 dans connectors/n8n.yaml : 49 outils.

Ce que déclare le fichier

Le catalogue métier la libelle « Sustainable-Use (fair-code, source-available) ».

Outils

Les noms n'ont pas de préfixe de connecteur. Répartition par ressource, mesurée sur les 49 outils :

Il n'existe pas d'outil qui lance un workflow à la demande : ni n8n_execute_workflow, ni équivalent. Le connecteur sait activer ou désactiver un workflow, relancer une exécution (executions_retry) et lire l'historique.

Le connecteur crée et supprime aussi des utilisateurs, des identifiants et des variables d'une instance n8n. Donnez à la clé d'API les seuls droits nécessaires.

Huit chemins de confort qui n'existent pas

Un avertissement du 2026-09-05, en tête du fichier, rapporte une mesure sur une instance vivante. Huit outils de commodité (comptage des exécutions, statistiques, workflows actifs, utilisateur courant) visaient des chemins absents de la spécification que sert n8n lui-même. Vérifié le 2026-10-03 : aucun de ces huit noms ne figure parmi les 49 outils actuels. La capacité existe en passant par les chemins réels (par exemple la liste des exécutions avec un filtre de statut) ; elle est à reprendre, pas à supposer.

Configuration

Dans l'application : page Identifiants (/credentials), fiche n8n Automation, champs « URL du serveur » et « API Key ».

Le connecteur envoie le User-Agent mgaas-connector/1.0. Un User-Agent contenant « bot » fait répondre n8n par un corps vide (mesure du 2026-07-03 consignée dans le fichier).

Déploiement

podman-compose.vps2.yml déploie un service n8n (image officielle, base Postgres partagée, volume qui conserve la clé de chiffrement de n8n). L'entrée du catalogue métier a le statut available.

Exemple

Active le workflow « Synchronisation clients ».

L'agent retrouve le workflow avec workflows_list, puis appelle workflows_activate.

Fichier source

connectors/n8n.yaml

Voir aussi

• Vue d'ensemble — chiffres mesurés, chargement et règles communes aux douze connecteurs
• Créer votre premier connecteur MCP — forme d'un fichier YAML et ajout d'un connecteur à la passerelle
• Routes MCP — ouvrir une session et appeler un outil par JSON-RPC
• Tarification — nombre de connecteurs métier inclus dans chaque offre
• Migration depuis d'autres outils — coexister avec une instance n8n existante pendant la migration

Connecteur Nextcloud

Nextcloud est une plateforme de fichiers et de collaboration sous licence AGPL-3.0. Le connecteur appelle ses interfaces WebDAV et OCS (REST).

Mesuré le 2026-10-03 dans connectors/nextcloud.yaml : 167 outils.

Ce que déclare le fichier

L'en-tête Accept est nécessaire : sans lui, OCS répond en XML étiqueté JSON (remarque consignée dans le fichier).

Outils

Tous les noms commencent par nc_. Répartition par famille, pour les principales :

Les 66 autres outils se répartissent en petites familles (notifications, activité, références, traduction, texte vers image, étiquettes, avatars, entre autres).

Fichiers : quatre outils seulement, nc_file_get, nc_file_upload, nc_file_download, nc_file_delete, tous sur le chemin WebDAV /remote.php/dav/files/{username}{path}. Aucun outil déclaré ne crée un dossier ni ne liste le contenu d'un dossier, parce que le fichier n'utilise que les méthodes GET, POST, PUT, PATCH et DELETE.

Contacts : trois outils (nc_contact_get, nc_contact_create, nc_contact_update) sur CardDAV. Agenda : un seul outil, nc_calendar_delete. Il n'existe pas d'outil pour lire ou créer des événements de calendrier.

Le connecteur gère aussi les comptes (nc_user_*, nc_group_*) et les applications (nc_app_install, nc_app_remove). Une identité d'administrateur lui donne ces pouvoirs ; préférez un compte restreint.

Configuration

Dans l'application : page Identifiants (/credentials), fiche Nextcloud, champs « URL du serveur », « Username » (qui alimente NEXTCLOUD_API_USER) et « App Password (revocable) » (qui alimente NEXTCLOUD_API_KEY). Générez ce mot de passe d'application dans les réglages de sécurité de Nextcloud : ce n'est pas votre mot de passe principal.

Les variables NEXTCLOUD_USERNAME et NEXTCLOUD_PASSWORD ne sont lues par aucun connecteur.

Déploiement

Ni podman-compose.vps2.yml ni podman-compose.yml ne déploient Nextcloud. Le connecteur vise une instance que vous fournissez. L'entrée du catalogue métier a le statut available.

Fichier source

connectors/nextcloud.yaml

Voir aussi

• Vue d'ensemble — chiffres mesurés, chargement et règles communes aux douze connecteurs
• Créer votre premier connecteur MCP — forme d'un fichier YAML et ajout d'un connecteur à la passerelle
• Routes MCP — ouvrir une session et appeler un outil par JSON-RPC
• Tarification — nombre de connecteurs métier inclus dans chaque offre
• Limites — la plateforme ne stocke pas de fichiers, ils restent dans l'outil connecté

Connecteur Odoo

Le connecteur Odoo pilote une instance Odoo par le protocole XML-RPC. Parmi les douze connecteurs décrits dans ce livre, c'est celui qui expose le plus d'outils : 711 outils nommés au registre, mesurés le 2026-10-03.

Deux endroits où se compter

Le fichier connectors/odoo.yaml ne déclare que 6 outils (crm.search_leads, crm.create_lead, sale.list_orders, account.list_invoices, hr.list_employees, project.list_tasks). Les 711 outils nommés vivent dans le registre Rust crates/forge-mcp/src/connector/odoo_tools_registry.rs. Un test du dépôt affirme ce nombre. Le site public affiche le même chiffre (OUTILS_ODOO dans crates/forge-ui/src/config/chiffres_mesures.rs).

Ce que déclare le fichier

Il n'y a pas de bloc auth : le connecteur lit quatre valeurs de connexion.

Configuration

Les variables ODOO_DB et ODOO_PASSWORD ne sont lues par aucun connecteur.

Parcours complet, avec la fiche Odoo ERP/CRM et un premier appel : Connecter Odoo à la passerelle MCP.

Pour un locataire, les valeurs sont saisies comme identifiants de la plateforme et stockées chiffrées. Une organisation peut en plus stocker un AppRole OpenBao : l'URL, la base et la clé sont alors lues depuis OpenBao en priorité, au moment de la requête (résolution des identifiants du code, entrée odooApi).

Outils nommés

Mesure du 2026-10-03 sur les 711 entrées du registre, par opération :

Les lectures (search, read, group) sont donc 273. Les 438 autres modifient des données. Les 711 outils visent 140 modèles Odoo. Les noms sont de la forme <module>_<objet>_<action>.

Exemples réels, tous présents au registre :

Les préfixes les mieux fournis sont hr (87 outils), inventory (51), sales (43), website (39), mrp (35) et crm (34).

Les anciens noms odoo_search_read, odoo_sale_order_list et odoo_invoice_validate n'existent pas au registre. Les noms informels sont rapprochés des noms canoniques à l'appel par odoo_tool_resolver.

Quatre outils génériques

Quatre outils prennent le modèle en argument : record_create, record_read, record_update, record_delete (crates/forge-mcp/src/connector/odoo_generic_crud.rs). Ils ne fonctionnent que sur une liste blanche de 402 modèles métier (odoo_metier_models.rs). Le framework, les rapports, la messagerie et la sécurité en sont exclus.

Écritures gardées

Parmi ces 402 modèles, 24 sont gardés en écriture : plan de comptes, journaux, taxes, lignes d'écriture comptable, relevés bancaires, entre autres. Une création, une modification ou une suppression sur l'un d'eux exige une approbation humaine via /actions/approvals. Elle n'est jamais exécutée seule par l'agent. La lecture de ces modèles reste libre.

Déploiement

podman-compose.vps2.yml déploie 17 services Odoo, un par secteur (thérapie, médical, juridique, immobilier, finance, entre autres). L'entrée du catalogue métier (odoo, catégorie CRM & ERP) a le statut available.

Limites techniques

• Le client HTTP du connecteur a un délai d'attente de 30 secondes.
• L'identifiant utilisateur obtenu à la connexion est gardé en mémoire 600 secondes, puis redemandé.

Exemple

Quels sont les contacts créés cette semaine dans Odoo ?

L'agent choisit un outil de recherche sur les contacts (contacts_search), construit le filtre et exécute l'appel XML-RPC.

Fichiers sources

connectors/odoo.yaml, crates/forge-mcp/src/connector/odoo_tools_registry.rs, crates/forge-mcp/src/connector/odoo_generic_crud.rs, crates/forge-mcp/src/connector/odoo_metier_models.rs

Voir aussi

• Vue d'ensemble — chiffres mesurés, chargement et règles communes aux douze connecteurs
• Créer votre premier connecteur MCP — forme d'un fichier YAML et ajout d'un connecteur à la passerelle
• Routes MCP — ouvrir une session et appeler un outil par JSON-RPC
• Tarification — nombre de connecteurs métier inclus dans chaque offre
• Connecter Odoo à la passerelle MCP — enregistrer les identifiants Odoo puis appeler un premier outil

Connecteur Rocket.Chat

Rocket.Chat est une messagerie d'équipe auto-hébergeable. Le connecteur appelle son API REST v1.

Mesuré le 2026-10-03 dans connectors/rocketchat.yaml : 338 outils.

L'API de Rocket.Chat écrit par POST, y compris pour supprimer : rc_channel_delete et rc_message_delete sont des POST.

Ce que déclare le fichier

Outils

Tous les noms commencent par rc_. Répartition par famille, pour les principales :

Les autres familles couvrent les intégrations et webhooks (rc_integration_*, 8 outils), les rôles (rc_role_*, 6), les abonnements, les réglages (rc_setting_*), la modération, l'omnicanal, les statistiques et l'administration. Sur les 62 familles de noms, 33 ne comptent qu'un ou deux outils.

La famille rc_livechat est la première par le nombre : elle concerne le chat en direct pour visiteurs et représente 83 outils sur 338.

Configuration

La variable ROCKETCHAT_AUTH_TOKEN n'est lue par aucun connecteur. Le délai d'attente déclaré est de 30 000 ms.

Dans l'application : page Identifiants (/credentials), fiche Rocket.Chat, champs « URL du serveur », « User ID » et « Auth Token ». Le champ « Auth Token » alimente ROCKETCHAT_API_KEY.

Déploiement

Ni podman-compose.vps2.yml ni podman-compose.yml ne déploient Rocket.Chat. Le connecteur vise une instance que vous fournissez. L'entrée du catalogue métier a le statut coming-soon.

Cas d'usage

• Envoyer un message dans un canal (rc_message_send).
• Rechercher dans l'historique (rc_message_search).
• Créer un canal ou une conversation directe.

Fichier source

connectors/rocketchat.yaml

Voir aussi

• Vue d'ensemble — chiffres mesurés, chargement et règles communes aux douze connecteurs
• Créer votre premier connecteur MCP — forme d'un fichier YAML et ajout d'un connecteur à la passerelle
• Routes MCP — ouvrir une session et appeler un outil par JSON-RPC
• Tarification — nombre de connecteurs métier inclus dans chaque offre
• Migration depuis d'autres outils — Rocket.Chat parmi les messageries d'équipe européennes de remplacement

Connecteur Typesense

Typesense est un moteur de recherche en texte intégral, tolérant aux fautes de frappe, sous licence GPL-3.0. Le connecteur appelle son API REST pour chercher, gérer les collections et les documents, et administrer le cluster.

Mesuré le 2026-10-03 dans connectors/typesense.yaml : 79 outils.

Ce que déclare le fichier

Outils

Les noms n'ont pas de préfixe de connecteur. Répartition par préfixe, mesurée sur les 79 outils :

search interroge /collections/{collection}/documents/search. Les opérations d'administration du cluster (operations_snapshot_create, operations_db_compact_create, operations_cache_clear_create) sont des outils d'écriture.

L'import en masse existe (collections_documents_import_create). Il n'existe pas d'outil de clonage de collection.

Configuration

Dans l'application : page Identifiants (/credentials), fiche Typesense Search, champs « URL du serveur » et « API Key ».

Le connecteur expose des outils d'écriture et de suppression (14 DELETE) : les droits effectifs sont ceux de la clé fournie.

Déploiement

podman-compose.vps2.yml déploie Typesense (image officielle épinglée, volume de données, port lié à la boucle locale). L'entrée du catalogue métier a le statut coming-soon.

Fichier source

connectors/typesense.yaml

Voir aussi

• Vue d'ensemble — chiffres mesurés, chargement et règles communes aux douze connecteurs
• Créer votre premier connecteur MCP — forme d'un fichier YAML et ajout d'un connecteur à la passerelle
• Routes MCP — ouvrir une session et appeler un outil par JSON-RPC
• Tarification — nombre de connecteurs métier inclus dans chaque offre
• Connaissances — collections et recherche vectorielle gérées par la plateforme elle-même

Architecture Chatbotaurus

Chatbotaurus est une plateforme MGaaS (MCP Gateway as a Service) européenne et souveraine, écrite en Rust. Elle combine un agent conversationnel, une passerelle MCP alimentée par des connecteurs déclarés en YAML, et une infrastructure auto-hébergeable sous Podman.

À la fin de ce chapitre, vous saurez situer chaque composant, dire dans quel plan il tourne et quelle page détaille son exploitation.

Vue d'ensemble

La plateforme tient en quatre couches :

• Interface : forge-ui, une seule base de code Dioxus 0.7 (binaire chatbotaurus). Elle se compile en wasm pour le navigateur (fonctionnalité web), ou en application bureau et mobile (fonctionnalités desktop et mobile de crates/forge-ui/Cargo.toml).
• Backend : forge-api, un serveur Axum qui expose /api/v1/** (REST, SSE, multipart, WebSocket), adossé à SeaORM sur PostgreSQL. Authentification, jeton CSRF, limitation de débit et contrôles de conformité UE sont des middlewares de ce crate.
• Passerelle MCP : le moteur forge-mcp (connecteurs, routage, sessions, transport Streamable HTTP). Il est monté dans forge-api (route /api/v1/mcp) et empaqueté seul dans forge-gateway, le binaire du service mcp-gateway du plan client.
• Infrastructure : conteneurs Podman répartis en deux plans (voir la section « Deux plans, une règle de nommage »), avec PostgreSQL, Valkey, Qdrant, OpenBao, Authentik, Ollama, la chaîne vocale et l'observabilité.

Deux plans, une règle de nommage

Le déploiement est découpé en deux projets Podman, chacun avec son réseau :

La règle tient au nom du service : un conteneur nommé mcp-* appartient au plan client, tout autre nom au plan backend. PostgreSQL et Valkey sont rattachés aux deux réseaux (alias DNS postgres et valkey sur mgaas-vps2) pour que les outils du plan client les joignent par leur nom.

Figure 1 : les deux plans de déploiement, leur règle de nommage et les deux services rattachés aux deux réseaux.

En production, ces plans sont décrits par des unités Quadlet (containers/*/*.container), l'ingress du plan backend est forge-traefik et celui du plan client mcp-caddy. Le détail est dans Déploiement avec Podman.

Crates du workspace

Le fichier Cargo.toml à la racine déclare ces membres :

Pile technique

Moteur MGaaS : quatre couches

Le moteur d'orchestration vit dans crates/forge-core/src/mgaas/ :

COUCHE 1 : raisonnement
  ToTLite, SelfConsistency, ChainOfVerification, MCTSLite

COUCHE 2 : orchestration d'agents
  routeur MoELite, TaskDecomposer, AgentMCPRegistry

COUCHE 3 : intelligence des outils
  RAREngine, DynamicToolPruner, ToolPatternMemory

COUCHE 4 : exécution et validation
  SpeculativeDecoder, ParallelStreamingExecutor, GroundingEngine

Sous pression de ressources, ce moteur est conçu pour désactiver ses techniques coûteuses par paliers : voir Gestion des erreurs.

État mesuré : la route GET /api/v1/mgaas/engines (crates/forge-api/src/routes/mgaas.rs) déclare « dormants », sans appelant de production, neuf des douze moteurs qu'elle liste. Seuls MoELiteRouter, TaskDecomposer et StructuredOutputValidator sont appelés en production.

Transport MCP : JSON-RPC 2.0 en Streamable HTTP

Dans forge-api, la route est montée dans crates/forge-api/src/router.rs :

POST   /api/v1/mcp   → JSON-RPC (initialize, tools/list, tools/call)
GET    /api/v1/mcp   → flux SSE de notifications
DELETE /api/v1/mcp   → terminer la session

• La session est portée par l'en-tête Mcp-Session-Id. Sa durée de vie par défaut est de 30 minutes d'inactivité (crates/forge-mcp/src/session.rs).
• La version de protocole annoncée à initialize est 2025-03-26 (crates/forge-mcp/src/protocol.rs).
• Ces routes exigent un utilisateur authentifié, et la surface MCP peut être coupée par l'interrupteur MCP_ENABLED.
• Le binaire forge-gateway expose, lui, POST /mcp et GET /health sur le port 8811 du plan client.

Pour explorer la flotte de connecteurs depuis l'API : GET /api/v1/mcp/catalogue (alias GET /api/v1/mcp/catalog) et GET /api/v1/mcp-gateway/servers.

Connecteurs MCP

Chaque fichier connectors/*.yaml déclare un connecteur. Au démarrage de forge-api, le CatalogueLoader (crates/forge-mcp/src/connector/catalogue.rs) lit ce dossier, résout les variables d'environnement et enregistre le connecteur dans le registre. Le nombre de connecteurs évolue avec le dépôt : il se compte avec ls connectors/*.yaml, jamais avec un chiffre recopié dans une page.

Un connecteur n'est accepté que s'il passe le contrôle de conformité UE du registre : voir Conception des connecteurs MCP.

Les connecteurs couvrent notamment les ERP et CRM (Odoo, ERPNext), les outils de collaboration, le support, l'analytique, les workflows (n8n), la sécurité, l'IA et un grand nombre de sources de données publiques européennes.

Modèles et chaîne vocale

• LLM : exécutés par Ollama (service forge-ollama). Le modèle par défaut se règle par la variable OLLAMA_MODEL, et forge-cli model pull télécharge un modèle.
• Embeddings : calculés localement (crate fastembed, crates/forge-core/src/rag/embedder.rs). La dimension des vecteurs est lue à l'exécution depuis le modèle chargé, pas fixée dans la documentation.
• Voix : synthèse par forge-kokoro-tts, transcription par forge-faster-whisper, temps réel par forge-livekit.

Les fournisseurs LLM tiers sont optionnels et désactivés par défaut.

Authentification

Les méthodes sont cumulables selon la configuration de l'organisation : mot de passe, second facteur TOTP (application d'authentification) et SSO OIDC via Authentik.

• Le jeton d'accès est un JWT signé en HS256 (l'algorithme est épinglé côté serveur). Sa durée se règle par JWT_EXPIRY ; le défaut du code est de 7 jours (crates/forge-api/src/state.rs).
• Protection CSRF par double soumission : cookie csrf-token et en-tête x-csrf-token sur les requêtes POST, PUT et DELETE.
• Les secrets de connecteurs sont chiffrés en AES-256-GCM avant stockage ; les locataires soumis à une exigence réglementaire peuvent les loger dans OpenBao.

Cloisonnement des locataires

Le filtre de locataire canonique repose sur l'organisation (organization_id), appliqué par accessible_workspace_filter (crates/forge-api/src/extractors/mod.rs). Un contrôle de pré-commit sur le cloisonnement des locataires protège les handlers du backend.

Gestion des erreurs

Chaque niveau capture et traduit ses erreurs :

• Transport MCP : JSON-RPC invalide, session expirée ;
• Connecteurs : délai dépassé, authentification, limite amont atteinte ;
• Moteur IA : dégradation par paliers sous pression de ressources.

Détails : Gestion des erreurs.

Compilation et contrôles

# Workspace complet
cargo build --workspace --release

# Interface web (wasm)
cargo build -p forge-ui --target wasm32-unknown-unknown --bin chatbotaurus

# Tests
cargo test --workspace

# Lint strict
cargo clippy --workspace --all-targets -- -D warnings

Les contrôles de pré-commit refusent notamment un fichier Rust de plus de 300 lignes sans exemption motivée et l'usage des termes « parity » ou « parité » sans preuve associée.

Voir aussi

• Conception des connecteurs MCP : manifestes YAML, connecteurs natifs et contrôle de conformité UE
• Gestion des erreurs : enveloppe d'erreur, codes JSON-RPC, disjoncteur et dégradation par paliers
• Routes MCP (Streamable HTTP) : transport, sessions et catalogue exposés par la passerelle
• Connecteurs MCP : comment un connecteur est chargé, authentifié et compté
• Déploiement avec Podman : les deux plans en pratique : Compose en développement, Quadlet en production

Gestion des erreurs

Chatbotaurus gère les erreurs à plusieurs niveaux : une énumération d'erreurs commune à tout le backend, une enveloppe JSON stable côté API, des codes JSON-RPC pour le transport MCP, un disjoncteur pour les services en aval et une dégradation par paliers du moteur d'IA.

À la fin, vous saurez lire un code d'erreur renvoyé par l'API ou par le transport MCP et savoir où chercher la cause.

Erreurs de l'API REST

Les handlers de forge-api renvoient des ForgeError (crates/forge-core/src/error.rs). Chaque variante porte un statut HTTP et un code lisible par machine :

Vault et VAULT_ERROR sont des noms historiques du code : le coffre de secrets du produit est OpenBao.

Les erreurs de domaine (Agent, Workflow, Rag, Embedding, HallucinationDetected, Ollama) répondent 500 avec les codes AGENT_ERROR, WORKFLOW_ERROR, RAG_ERROR, EMBEDDING_ERROR, HALLUCINATION_DETECTED et OLLAMA_ERROR.

Le corps de réponse a toujours la même forme :

{
  "error": {
    "code": "NOT_FOUND",
    "message": "resource not found: user id=42",
    "status": 404
  }
}

Une réponse 429 ajoute le champ retryAfterSecs dans le corps et l'en-tête HTTP Retry-After. La conversion en réponse HTTP est faite par crates/forge-common/src/error.rs : niveau de trace warn pour un 404, info pour les autres 4xx, error pour les 5xx.

Pour agir sur un code précis (TIMEOUT, SERVICE_UNAVAILABLE, RATE_LIMITED, CIRCUIT_OPEN, session MCP expirée), voir Problèmes connus.

Messages sans fuite d'information

Un message d'erreur de base de données, de client HTTP ou de fichier peut embarquer une requête SQL, une URL interne ou un chemin local. Les handlers passent donc par safe_message (crates/forge-api/src/safe_error.rs) : le client reçoit un texte fixe et neutre. En développement local seulement, l'opérateur peut démarrer le serveur avec FORGE_VERBOSE_ERRORS=1 pour obtenir le détail.

Le même module fournit error_body et error_body_with_request_id (ajoute un champ request_id pour relier une réponse à ses traces).

Transport MCP

Le transport Streamable HTTP répond en JSON-RPC 2.0. Codes émis par crates/forge-mcp/src/transport/ et crates/forge-api/src/routes/mcp.rs :

Les messages du code -32603 sont génériques (passés par safe_message). Une session expire après 30 minutes d'inactivité : le client doit alors renvoyer initialize.

Connecteurs

• Limite amont atteinte : si le service tiers répond 429, le connecteur renvoie RATE_LIMITED avec le Retry-After de l'amont (60 secondes à défaut). Un connecteur peut aussi déclarer rate_limit_per_min : la limite est alors vérifiée avant l'appel réseau.
• Délai dépassé : chaque connecteur a un timeout_ms (30 000 par défaut). Un dépassement est renvoyé en TIMEOUT (504).
• Service injoignable : une erreur de connexion devient SERVICE_UNAVAILABLE (503).
• URL interdite : une URL de base fournie par un locataire qui vise le réseau interne est refusée avant tout appel (Forbidden, message SSRF_BLOCKED).

Agents : disjoncteur

Chaque agent exécuté par un AgentWorker (crates/forge-core/src/agent/worker.rs) est protégé par un disjoncteur à trois états (fermé, ouvert, semi-ouvert). Par défaut il s'ouvre après quelques échecs consécutifs, reste ouvert un court délai avant de passer en semi-ouvert, et considère un appel comme échoué au-delà d'un délai borné. Tant qu'il est ouvert, l'appel échoue immédiatement avec CIRCUIT_OPEN (503). Une primitive générique équivalente existe dans crates/forge-core/src/security/circuit_breaker.rs.

Moteur d'IA : dégradation par paliers

Cette cascade est livrée mais non branchée : les moteurs de raisonnement qu'elle coupe n'ont pas d'appelant de production (voir Supervision). Le moniteur de ressources du moteur MGaaS (crates/forge-core/src/mgaas/resource_monitor.rs) choisit un niveau de dégradation à partir de la RAM utilisée, du CPU et de la latence moyenne. Il existe cinq niveaux, par ordre décroissant de capacités :

1. FULL : toutes les techniques de raisonnement actives ;
2. NO_MCTS : MCTSLite désactivé ;
3. NO_TOT : ToTLite désactivé en plus ;
4. NO_SELF_CONSISTENCY : l'auto-cohérence est désactivée en plus ;
5. TEMPLATE_ONLY : réponses issues de gabarits, dernier recours.

Les seuils (mémoire, processeur, latence) sont fixés dans le code du moniteur de ressources et ne sont pas publiés ici.

Règle appliquée : si un seul seuil critique est franchi, le niveau est TEMPLATE_ONLY. Sinon, si un seuil d'avertissement est franchi, le niveau est NO_SELF_CONSISTENCY quand la mémoire dépasse nettement son seuil d'avertissement, NO_TOT quand le processeur est très chargé, et NO_MCTS dans les autres cas, latence comprise (marges fixées dans le code).

Figure 2 : les cinq niveaux de dégradation du moteur d'IA, par ordre décroissant de capacités.

Le moteur anti-hallucination (crates/forge-core/src/anti_hallucination/) a son propre indicateur de niveau opérationnel, distinct du précédent : Full, NoCache, NoRag, NoSemantic, TemplateOnly, Maintenance. Il décide quelles fonctions sont annoncées au client, et ne se confond pas avec le moniteur de ressources ci-dessus.

Observabilité

• Les journaux du backend sont écrits en JSON par défaut ; LOG_FORMAT=pretty ou compact donne une sortie lisible (init_tracing, crates/forge-api/src/main.rs). TRACING_JSON, fixée dans podman-compose.yml, n'est pas lue par forge-api.
• Chaque requête reçoit un identifiant par la couche RequestIdLayer.
• Le plan backend embarque VictoriaMetrics (métriques) et VictoriaLogs (logs) ; la détection d'intrusion repose sur CrowdSec. L'unité Falco existe mais est retirée du déploiement depuis le 2026-09-19.

Voir aussi

• Architecture Chatbotaurus : où vivent les couches qui produisent ces erreurs
• Conception des connecteurs MCP : délai, limite amont et contrôle SSRF déclarés côté connecteur
• Problèmes connus : session expirée, connecteur en échec, disjoncteur ouvert : que faire
• Documentation Swagger : contrat OpenAPI et authentification : format des erreurs et limites de débit vus du client
• Supervision : état réel de la cascade de dégradation et des métriques exposées

Conception des connecteurs MCP

Ce chapitre décrit comment un service externe devient un ensemble d'outils MCP dans Chatbotaurus. Le moteur est le crate forge-mcp. À la fin, vous saurez écrire le manifeste d'un connecteur et ce que le contrôle de conformité UE en refuse.

Deux types de connecteurs

1. Connecteur déclaratif YAML (cas général)

Un fichier connectors/<nom>.yaml décrit le service et ses outils. Au démarrage, forge-api lit le dossier désigné par la variable CONNECTOR_CATALOGUE_DIR (par défaut ./connectors). Il enregistre chaque connecteur dans le registre. Le fichier connectors/TEMPLATE.yaml est un modèle à copier. Pas à pas : Créer votre premier connecteur MCP. Le dossier n'est lu qu'au démarrage : redémarrez forge-api après chaque modification (voir Fichiers de configuration).

Exemple tiré de connectors/matomo.yaml, abrégé (l'URL par défaut y est remplacée par une adresse d'exemple) :

id: matomo
display_name: "Matomo Analytics"
base_url: "${MATOMO_URL:-https://matomo.exemple.eu}"
base_url_env: MATOMO_URL
auth:
  type: query_token
  param: token_auth
  token_env: MATOMO_API_KEY
compliance:
  data_residency: self-hosted
  self_hosted: true
  gdpr_compliant: true
  license: "GPL-3.0"
  gaia_x: true
timeout_ms: 30000
tools:
  - name: get_visits_summary
    description: "Matomo Reporting API VisitsSummary.get"
    method: GET
    path: "/index.php"
    param_location: query
    input_schema:
      type: object
      properties:
        module: { type: string, default: "API" }
        method: { type: string, default: "VisitsSummary.get" }
        format: { type: string, default: "JSON" }

Champs principaux (structure HttpConnectorConfig, crates/forge-mcp/src/connector/http.rs) :

Types d'authentification : none, bearer, api_key, basic, query_token, jwt_exchange, oauth2, login_token, checksum, json_rpc_session. Les fichiers YAML ne portent jamais de secret : ils nomment la variable d'environnement qui le contient (token_env, key_env, entre autres).

Les outils sont exposés avec le préfixe de leur connecteur : l'outil get_visits_summary du connecteur matomo s'appelle matomo.get_visits_summary.

2. Connecteur natif Rust

Pour un protocole qui n'est pas du REST (par exemple l'XML-RPC d'Odoo, crates/forge-mcp/src/connector/odoo_xmlrpc_client.rs) ou une transformation lourde, on implémente le trait McpConnector (crates/forge-mcp/src/connector/mod.rs) :

#[async_trait::async_trait]
pub trait McpConnector: Send + Sync + 'static {
    fn id(&self) -> &str;
    fn display_name(&self) -> &str;
    fn compliance(&self) -> &EuCompliance;
    async fn list_tools(&self) -> ForgeResult<Vec<ToolDefinition>>;
    async fn execute(
        &self,
        tool_name: &str,
        arguments: serde_json::Value,
    ) -> ForgeResult<Vec<ContentBlock>>;
    async fn health_check(&self) -> ForgeResult<ConnectorHealth>;
    // ... plus des méthodes avec valeur par défaut (voir le fichier)
}

Un connecteur natif est enregistré dans le ConnectorRegistry au même titre qu'un connecteur YAML.

Contrôle de conformité UE

ConnectorRegistry::register appelle EuCompliance::validate. Un connecteur dont gdpr_compliant vaut false, ou dont la résidence des données n'est pas européenne (ou self-hosted), est rejeté au démarrage et journalisé. La classification de la résidence est centralisée dans crates/forge-mcp/src/connector/residence.rs. Côté exécution, chaque appel de serveur repasse par la fonction unique forge_core::compliance::is_server_allowed.

Cycle de vie

1. Enregistrement : au démarrage, le CatalogueLoader charge les YAML et le registre reçoit aussi les connecteurs natifs.
2. Découverte : le client MCP appelle tools/list sur POST /api/v1/mcp. Le catalogue se consulte aussi par GET /api/v1/mcp/catalogue.
3. Exécution : le client appelle tools/call sur la même route.
4. Résultat : le connecteur renvoie des blocs de contenu MCP (ContentBlock).

Figure 3 : du connecteur à l'outil MCP, avec le contrôle de conformité UE à l'enregistrement et à chaque appel.

Identifiants et secrets

• Les identifiants tiers d'un locataire sont chiffrés en AES-256-GCM avant stockage. Au démarrage, crates/forge-api/src/connector_credential_env.rs les déchiffre et les publie dans les variables d'environnement que lisent les connecteurs. Les locataires réglementés peuvent utiliser une couche OpenBao.
• À chaque requête, les secrets du seul locataire appelant sont installés pour la durée de l'appel. Avec FORGE_MULTI_TENANT_STRICT=1, le chargement global au démarrage est sauté et aucun connecteur ne retombe sur les identifiants globaux du déploiement.

Sécurité

• SSRF : une URL de base fournie par un locataire (base_url_env) est contrôlée en deux temps avant tout appel réseau. Premier temps : analyse de l'URL (schéma, adresse, hôtes internes). Second temps : résolution DNS avec refus des adresses privées. Une violation renvoie Forbidden avec le motif SSRF_BLOCKED. Ce contrôle ne s'applique qu'aux URL fournies par un locataire : l'URL du YAML ou de l'environnement de l'opérateur n'y est pas soumise. Aucune option d'exploitation ne le désactive ; seule la compilation des tests le lève.
• Actions irréversibles : un outil irréversible ne s'exécute qu'après une approbation humaine explicite, limitée au nom exact de l'outil (crates/forge-mcp/src/connector/human_authorization.rs). Un outil destructif n'est jamais autorisable par cette voie.
• Un connecteur peut être limité à la lecture : le connecteur Matomo, par exemple, ne publie que des outils de rapport.

Bonnes pratiques

• Connexions : un seul client reqwest réutilisé par connecteur.
• Limites amont : déclarez rate_limit_per_min quand l'API publie un plafond ; une réponse 429 est renvoyée en RATE_LIMITED avec son Retry-After.
• Cache : cache_ttl_s convient aux données publiques en lecture seule ; laissez-le à 0 pour tout le reste.
• Données publiques : le champ grounded fait accompagner chaque réponse de sa source (source_url, retrieved_at).

Voir aussi

• Créer votre premier connecteur MCP : écrire, valider et tester un manifeste pas à pas
• Connecteurs MCP : ce qui est mesuré et comment un connecteur est chargé
• Routes MCP (Streamable HTTP) : découverte et appel des outils, catalogue consultable par l'API
• Gestion des erreurs : codes renvoyés par un connecteur : délai, limite amont, SSRF
• Fichiers de configuration : où vivent les manifestes et comment l'environnement y est interpolé

Documentation Swagger : contrat OpenAPI et authentification

forge-api sert son contrat OpenAPI lui-même, généré depuis le code avec la bibliothèque utoipa. Il n'existe pas d'interface Swagger UI servie par le backend : vous récupérez le document et l'ouvrez dans l'outil de votre choix (Swagger Editor, Postman, Insomnia, générateur de client).

Dans les exemples de ce livre, <hote-api> désigne le nom d'hôte de l'API, sans schéma : app.<domaine> derrière le nom public (voir Diagnostics et signalement). Sur un poste de développement, écrivez http://localhost:3000 à la place de https://<hote-api>.

Où récupérer le contrat

Ces routes sont publiques. La variable OPENAPI_ENABLED=false les coupe : elles répondent alors 404. Le champ servers du document vaut / parce que les chemins documentés portent déjà le préfixe /api/v1.

curl "https://<hote-api>/api/v1/openapi.json" -o forge-openapi.json

Ce que couvre le contrat, et ce qu'il ne couvre pas

Le contrat est partiel. Il se limite aux opérations annotées avec #[utoipa::path] dans crates/forge-api/src/openapi/. Mesures reproductibles :

Familles documentées (étiquettes du contrat) : santé, facturation, authentification, OAuth/OIDC, SSO, sessions, chat, passerelle de chat, messages de gateway, prédictions, documents (RAG, document store, scraping, chunks), clés d'API, compte, rôles.

Familles absentes du contrat : le transport MCP (/api/v1/mcp), le catalogue métier (/api/v1/mcp/catalog-business/*), la gestion des gateways (/api/v1/gateways/*), les retours (/api/v1/feedback), les outils, variables et identifiants. Pour ces routes, la référence est ce livre, qui les décrit une par une d'après le routeur.

Le document déclare trois schémas de sécurité : BearerAuth (JWT dans Authorization: Bearer), CookieAuth (cookie jwt) et ApiKeyAuth (en-tête X-API-Key). Seuls les deux premiers sont consommés par des routes aujourd'hui : ApiKeyAuth est déclaré sans route qui l'accepte.

Authentification

La majorité des routes exigent un jeton, donc un compte (Prise en main guidée, étape 1). Il s'obtient par la connexion, avec un second facteur (OTP e-mail ou application TOTP) lorsqu'il est exigé :

# 1. connexion
curl -X POST "https://<hote-api>/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"<email>","password":"<mot-de-passe>"}'

La réponse porte requires_2fa. Quand il vaut false et que la connexion réussit, elle contient directement token : passez à l'envoi du jeton plus bas. Un e-mail inconnu ou un mot de passe erroné répond 401 (UNAUTHORIZED), et si requires_mfa_enrollment vaut true, aucun jeton n'est rendu : enrôlez d'abord un second facteur. Quand requires_2fa vaut true, la réponse contient aussi two_factor_token et method (email ou totp) :

# 2. validation du second facteur
curl -X POST "https://<hote-api>/api/v1/auth/2fa/verify" \
  -H "Content-Type: application/json" \
  -d '{"two_factor_token":"<two_factor_token>","code":"<code>"}'

La réponse est {"authenticated": true, "token": "<token>"}. Le renvoi du code par e-mail se fait par POST /api/v1/auth/2fa/resend. La connexion par fournisseur d'identité (OIDC) passe par GET /api/v1/auth/oidc/login.

Ensuite, joignez le jeton à chaque appel (les tutoriels le rangent dans la variable JWT) :

Authorization: Bearer <token>

Les navigateurs utilisent le cookie jwt posé par la connexion. Le jeton vit 7 jours par défaut (variable JWT_EXPIRY). POST /api/v1/auth/refresh (alias POST /api/v1/auth/refreshToken) renouvelle une session encore valide et rend {"token": ...} ; il n'existe pas de jeton de rafraîchissement séparé : un jeton expiré ne peut pas être renouvelé, il faut se reconnecter.

Quelques routes sont publiques (santé, contrat OpenAPI, conformité publique, prediction/{id} d'une gateway publiée, SBOM).

Provisionnement SCIM

Le provisionnement d'utilisateurs et de groupes suit SCIM 2.0 sous /api/v1/scim/v2/ : Users, Groups, ServiceProviderConfig, Schemas et ResourceTypes. Il s'authentifie par un jeton porteur SCIM dédié.

Format des erreurs

Une erreur est un objet {"error": {"code": "...", "message": "..."}} ; les erreurs de l'extracteur d'authentification ajoutent status. Codes fréquents : UNAUTHORIZED (401), FORBIDDEN (403), NOT_FOUND (404), VALIDATION_FAILED (422), FEATURE_PENDING (503, capacité prévue non livrée). Le dépassement de débit est différent : le limiteur répond 429 avec un corps vide et l'en-tête retry-after (en secondes). Le transport MCP répond, lui, en erreurs JSON-RPC (error.code, error.message) : voir Routes MCP.

Limites de débit

Le limiteur est par adresse IP et par préfixe de route (le préfixe de longueur maximale l'emporte) :

Les routes d'authentification ont en plus leurs propres limiteurs (auth_rate_limiter, account_rate_limiter).

Voir aussi

• API-as-a-Service EU souverain : principe, appel d'un connecteur et garde-fous en place
• Routes MCP : transport MCP, absent du contrat, décrit route par route
• Connecter Odoo à la passerelle MCP : du jeton à un premier appel d'outil, pas à pas
• Gestion des erreurs : le détail des codes d'erreur de l'API et du transport MCP
• Routes des gateways et de la prédiction : gateways et prédiction, absentes du contrat, décrites route par route
• Routes des ressources : document stores, identifiants et variables, décrits route par route
• Sécurité : authentification, limiteurs et protection des requêtes côté plateforme

API-as-a-Service EU souverain

Ce chapitre décrit ce que la plateforme fait aujourd'hui pour exposer des sources de données européennes sous forme d'appels JSON structurés, et ce qui reste prévu. À la fin, vous savez ouvrir une session MCP, appeler un outil de connecteur (par session ou par appel direct) et lister le registre. Chaque route citée existe dans crates/forge-api/src/router.rs et chaque chiffre vient d'une commande que vous pouvez relancer.

Le principe

Une source de données (API publique d'une institution, service auto-hébergé) est décrite par un fichier YAML de connecteur dans connectors/. Au démarrage, forge-api charge ces fichiers dans un registre ; chaque outil déclaré devient un outil MCP nommé {id-du-connecteur}.{outil} (exemple : data-europa.search_datasets). Le client n'a pas à connaître l'API amont : il appelle l'outil, la plateforme exécute la requête et rend le résultat en JSON.

Mesures reproductibles :

Les deux nombres sont distincts : le registre exécutable (les YAML) et le catalogue business (une liste de fiches de serveurs, voir le chapitre « Routes du catalogue métier »). Ne les confondez pas.

Appeler un connecteur

Deux chemins authentifiés mènent au même registre. Il faut un jeton (Swagger, section Authentification) et l'adresse de votre API : <hote-api> désigne le nom d'hôte de l'API, sans schéma (app.<domaine> derrière le nom public, voir Diagnostics et signalement). Sur un poste de développement, écrivez http://localhost:3000 à la place de https://<hote-api>.

1. Transport MCP (JSON-RPC, session). Ouvrez une session avec initialize, puis appelez tools/call en passant l'en-tête Mcp-Session-Id reçu :

# 1. ouvrir la session (l'identifiant de session revient dans l'en-tête de réponse)
curl -i -X POST "https://<hote-api>/api/v1/mcp" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"mon-client","version":"1.0.0"}}}'

# 2. appeler un outil de connecteur
curl -X POST "https://<hote-api>/api/v1/mcp" \
  -H "Authorization: Bearer <token>" \
  -H "Mcp-Session-Id: <session-id>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"data-europa.search_datasets","arguments":{"q":"energie","limit":5}}}'

La forme des réponses (result.type, result.content, error.code) est décrite dans Routes MCP.

2. Appel direct, sans session. POST /api/v1/mcp/catalog-business/tools/call prend {server, tool, args} et exécute l'outil dans le registre :

curl -X POST "https://<hote-api>/api/v1/mcp/catalog-business/tools/call" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"server":"data-europa","tool":"search_datasets","args":{"q":"energie","limit":5}}'

La réponse est {"success": true, "server": ..., "tool": ..., "result": ...} en cas de succès, ou {"success": false, "error": ...} (statut HTTP 200) si le connecteur est absent ou si l'exécution échoue. Un serveur absent de la liste des serveurs autorisés est refusé avant même la recherche dans le registre, par un 403 de corps {"error": {"code": "FORBIDDEN", ...}} dont le message dit « hors du plan ou non conforme EU ». Cette liste ne dépend pas du locataire (voir Connecteurs MCP).

Pour lister ce que le registre contient :

curl "https://<hote-api>/api/v1/mcp/catalogue" -H "Authorization: Bearer <token>"

La réponse est {"catalogue": [...], "total": N} ; chaque entrée porte l'id, le display_name et le bloc compliance (résidence des données, auto-hébergé, RGPD, licence, Gaia-X).

Sources européennes disponibles

Des connecteurs de sources publiques européennes existent dans connectors/ : eurlex, eurostat, cordis, openaire, europeana, ecb-data, europe-pmc, data-europa. Un méta-moteur de recherche auto-hébergé, searxng, déclare les outils query, config et health.

Ce qui n'existe pas : il n'y a pas de connecteur dédié aux sites de l'EDPB, de la CURIA, de l'EBA ou de l'ESMA. Les sources ci-dessus sont celles que le dépôt livre ; toute autre source passe par l'ajout d'un fichier YAML de connecteur.

Garde-fous réellement en place

• Authentification : les deux chemins exigent un jeton (Authorization: Bearer ou cookie jwt). Une session MCP est liée à l'utilisateur qui l'a ouverte.
• Conformité UE : chaque appel d'outil passe par un point d'étranglement de conformité avant l'exécution (is_server_allowed dans forge-core).
• Plafond amont : le champ rate_limit_per_min du YAML d'un connecteur plafonne les appels sortants vers la source.
• Secrets : les identifiants d'un locataire sont chiffrés au repos (AES-256-GCM) et résolus à la requête ; ils ne sont jamais renvoyés en clair.
• Inventaire logiciel : le SBOM CycloneDX du binaire servi est public sur GET /.well-known/sbom (hors préfixe /api/v1).
• Analyse d'images : l'analyse Trivy des images est exécutée en CI (workflow de CI du dépôt), pas au moment d'un appel d'API.

Ce qui est prévu, et ce qui est retiré

Voir aussi

• Routes MCP : transport Streamable HTTP, sessions et méthodes JSON-RPC détaillées
• Routes du catalogue métier : lecture opérationnelle et cycle de vie prévu
• Documentation Swagger : contrat OpenAPI, obtention du jeton et limites de débit
• Connecter Odoo à la passerelle MCP : un connecteur qui exige les identifiants du locataire, de leur enregistrement au premier appel
• Gestion des erreurs : lire un code d'erreur de l'API ou du transport MCP
• Connecteurs MCP : connecteurs décrits dans ce livre et sources publiques de l'UE
• Créer votre premier connecteur MCP : ajouter une source par un fichier YAML de connecteur

Routes MCP (Streamable HTTP)

Le transport MCP de la plateforme suit le protocole Streamable HTTP, révision 2025-03-26 (constante MCP_PROTOCOL_VERSION dans forge-mcp). Les échanges sont du JSON-RPC 2.0. La route est déclarée dans crates/forge-api/src/router.rs et ses gardes d'authentification dans crates/forge-api/src/routes/mcp.rs.

Désactivation. Le groupe /api/v1 se coupe avec API_ENABLED=false, et le transport MCP avec MCP_ENABLED=false (ou API_ENABLED=false). Une surface coupée répond un 404 JSON, jamais un 403.

Transport principal

Les trois exigent un jeton (Authorization: Bearer <token> ou cookie jwt). <hote-api> est défini dans Swagger. Une session est liée à l'utilisateur qui l'a ouverte : l'identité passée dans les paramètres d'initialize est écrasée par celle du jeton, et une session qui n'appartient pas à l'appelant répond 404 avec le code JSON-RPC -32600 (« session inconnue »).

Figure 4 : une session MCP, de initialize à DELETE.

POST /api/v1/mcp

En-têtes : Content-Type: application/json, et Mcp-Session-Id: <session-id> pour toutes les méthodes sauf initialize et ping.

Un seul objet JSON-RPC par requête. Le corps est désérialisé en une requête unique : un tableau (batch JSON-RPC) n'est pas accepté. Pour enchaîner plusieurs appels, envoyez plusieurs requêtes.

Méthodes JSON-RPC traitées (liste du match de mcp_post_handler) :

Toute autre méthode répond -32601 (« method not found »). Un corps qui n'est pas une requête JSON-RPC valide répond 400 avec -32700.

initialize

curl -i -X POST "https://<hote-api>/api/v1/mcp" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"mon-client","version":"1.0.0"}}}'

La réponse contient protocolVersion, les capabilities (tools, resources, prompts, completion, logging) et serverInfo (name: "chatbotaurus-forge"). L'identifiant de session est dans l'en-tête de réponse mcp-session-id. Copiez-le dans une variable (export SESSION=<session-id>) : les appels suivants le renvoient dans l'en-tête Mcp-Session-Id.

tools/list

curl -X POST "https://<hote-api>/api/v1/mcp" \
  -H "Authorization: Bearer <token>" \
  -H "Mcp-Session-Id: <session-id>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

La réponse porte result.tools, une liste d'objets name, description, inputSchema et connector_id. Les noms d'outils ont la forme {id-du-connecteur}.{outil}. Prenez les noms exacts dans la réponse de tools/list, jamais dans un exemple de document.

tools/call

curl -X POST "https://<hote-api>/api/v1/mcp" \
  -H "Authorization: Bearer <token>" \
  -H "Mcp-Session-Id: <session-id>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"data-europa.search_datasets","arguments":{"q":"energie","limit":5}}}'

Réponse : statut HTTP 200 et un objet JSON-RPC. En cas de succès, result.type vaut success et result.content est une liste de blocs (type, text). Avant l'exécution, un échec est un objet error à la place de result, et error.code reprend le code HTTP de l'échec tout en gardant le statut HTTP 200 : 401 session expirée, 403 serveur absent de la liste autorisée, 404 outil inconnu. Si le connecteur lui-même échoue, result.type vaut error et result porte code et message, toujours avec le statut HTTP 200.

Sans Mcp-Session-Id, la réponse est 400 (-32600, « missing Mcp-Session-Id »). Une session expirée ou inconnue répond 401 : en statut HTTP pour tools/list, dans error.code pour tools/call.

GET /api/v1/mcp

Ouvre un flux text/event-stream pour la session désignée par Mcp-Session-Id. Le flux envoie un événement open ({"sessionId": ...}) puis un commentaire de maintien de connexion toutes les 30 secondes.

Capacité en sommeil. Les capacités annoncent tools.listChanged, mais aucune notification n'est poussée aujourd'hui sur ce flux : seuls l'événement open et les signaux de maintien sont émis (commentaire du code dans mcp_get_handler). Ne bâtissez pas de logique client sur des notifications serveur.

DELETE /api/v1/mcp

Ferme la session de Mcp-Session-Id, libère ses ressources et inscrit la fermeture au journal d'audit. Réponse 204 No Content.

Sessions

• Chaque session est un UUID, stocké dans Valkey.
• Durée de vie par défaut : 30 minutes (DEFAULT_SESSION_TTL dans forge-mcp/src/session.rs). Chaque tools/call rafraîchit ce délai.
• La session est vérifiée à chaque requête ; si le magasin de sessions est indisponible, la réponse est 503 (-32603).

Catalogue des connecteurs

Ces routes exigent un jeton. GET /api/v1/mcp/catalogue renvoie {"catalogue": [{"id", "display_name", "compliance": {...}}], "total": N}.

curl "https://<hote-api>/api/v1/mcp/catalogue" -H "Authorization: Bearer <token>"

La fiche descriptive des serveurs business (catégorie, fournisseur, pays, certifications) est servie par /api/v1/mcp/catalog-business, décrit dans le chapitre « Routes du catalogue métier ».

Documentation de l'API

Il n'existe pas de serveur de documentation séparé. Le contrat OpenAPI est servi par forge-api lui-même (voir le chapitre « Swagger »).

Voir aussi

• API-as-a-Service EU souverain : appeler un connecteur par session ou par appel direct
• Créer votre premier connecteur MCP : ajouter un connecteur, puis le tester par ce transport
• Connecter Odoo à la passerelle MCP : une session et un premier appel d'outil, pas à pas
• Diagnostics et signalement : ouvrir une session et consulter le catalogue en dépannage
• Gestion des erreurs : codes JSON-RPC du transport et enveloppe d'erreur de l'API
• Conception des connecteurs MCP : cycle de vie des connecteurs derrière tools/list et tools/call

Routes du catalogue métier

Le catalogue business est la liste des serveurs MCP que la plateforme sait décrire et proposer. Toutes les routes vivent sous /api/v1/mcp/catalog-business (il n'existe aucun préfixe mcp/gateways : d'anciennes versions de ce livre le citaient à tort). Elles sont déclarées dans crates/forge-api/src/router.rs et implémentées dans crates/forge-api/src/routes/mcp_catalog_business.rs.

Authentification. Toutes ces routes exigent un jeton (Authorization: Bearer <token> ou cookie jwt). Les opérations de cycle de vie sont de plus réservées aux rôles admin et owner : un autre rôle reçoit 403 FORBIDDEN.

<hote-api> est défini dans Swagger.

État réel. La lecture du catalogue est opérationnelle. Les opérations qui piloteraient des conteneurs (deploy, start, stop, restart, secrets, security, déploiement de profil) répondent aujourd'hui 503 avec le code FEATURE_PENDING : l'adaptateur Podman n'est pas branché sur forge-api. C'est une capacité prévue (spec 16, tâche P5.5 ; voir la section « Cycle de vie : prévu, répond 503 » plus bas), pas une capacité livrée.

Lecture du catalogue

GET /api/v1/mcp/catalog-business

Paramètre de requête : category (valeur exacte d'une catégorie, par exemple Communication ou CRM%20%26%20ERP une fois encodé ; all ou vide = pas de filtre). Le paramètre tier est accepté mais n'est pas appliqué : le catalogue renvoie tous les serveurs et le client filtre.

curl "https://<hote-api>/api/v1/mcp/catalog-business?category=Communication" \
  -H "Authorization: Bearer <token>"

Réponse : {"servers": [...], "total": N}. Il n'y a pas de pagination. Une fiche porte ces champs, lus dans routes/data/catalog-business.json :

{
  "id": "odoo",
  "name": "Odoo",
  "description": "ERP/CRM open source complet: ventes, achats, stock, comptabilite, RH et plus.",
  "category": "CRM & ERP",
  "iconName": "Briefcase",
  "provider": "Odoo SA",
  "country": "Belgique",
  "endpoints": 331,
  "status": "available",
  "certifications": ["RGPD", "ISO27001", "SOC2", "Gaia-X"],
  "license": "LGPL-3.0",
  "documentation": "https://www.odoo.com/documentation",
  "verified": true,
  "pullCount": 1247,
  "tags": ["erp", "crm", "comptabilite", "rh", "stock", "ventes"],
  "version": "17.0",
  "tier": "official"
}

Le catalogue embarqué contient 108 fiches (test catalog_embeds_full_business_catalogue). GET .../{id} renvoie la fiche seule, ou 404 NOT_FOUND si l'identifiant est inconnu.

Les champs certifications, verified et pullCount sont des valeurs écrites dans le fichier embarqué. Aucun code de la plateforme ne les calcule ni ne les vérifie : ne les lisez ni comme une certification obtenue, ni comme un compteur de téléchargements mesuré.

GET /api/v1/mcp/catalog-business/{id}/status

Rend l'état honnête d'un serveur : sa disponibilité au registre, pas celle d'un conteneur.

{
  "serverId": "odoo",
  "containerId": null,
  "port": null,
  "uptime": null,
  "startedAt": null,
  "status": "available",
  "proven_operational": true,
  "runtime": { "known": false, "reason": "podman_adapter_not_wired" }
}

status vaut available si le connecteur est dans le registre, sinon not_registered. Un identifiant absent du catalogue rend 404.

GET /api/v1/mcp/catalog-business/profiles

Les profils sont lus dans le fichier de profils du dépôt. La réponse est {"profiles": [...]}. Il y en a quatre :

Ces 37 serveurs sont ceux du fichier de profils, pas les 108 fiches du catalogue embarqué : ce sont deux inventaires différents.

GET /api/v1/mcp/catalog-business/deployed

Rend la liste des identifiants de serveurs prouvés opérationnels par un audit en direct (OPERATIONAL_PROVEN_LIVE, dans forge-core), sous la forme d'un tableau JSON d'identifiants. Ce n'est pas un inventaire de conteneurs Podman.

Exécuter un outil

POST /api/v1/mcp/catalog-business/tools/call prend server, tool et args (forme de la réponse : voir API-as-a-Service EU souverain) :

curl -X POST "https://<hote-api>/api/v1/mcp/catalog-business/tools/call" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"server":"searxng","tool":"query","args":{"q":"reglement ia"}}'

GET .../{id}/registry-tools liste les outils d'un connecteur et répond {"id": ..., "registry_tools": [...]} ; pour un identifiant absent du registre, la réponse reste 200 avec "registry_tools": [] et un champ error. GET .../tools répond {"tools": [...], "total": N} : les outils des connecteurs autorisés. La route voisine GET .../{id}/tools répond toujours {"id": ..., "tools": []} : elle est un emplacement de compatibilité, utilisez registry-tools.

Note sur GET /api/v1/stats/catalog-business. Cette route compte les lignes de la table des modèles personnalisés et renvoie {"total": N, "last_24h": M}. Elle ne décrit pas le catalogue de serveurs.

Cycle de vie : prévu, répond 503

Un appelant sans rôle admin ou owner reçoit d'abord 403 (et la tentative est auditée) ; un administrateur reçoit le 503. La réponse porte l'en-tête Retry-After: 86400 et ce corps :

{
  "error": {
    "code": "FEATURE_PENDING",
    "message": "MCP catalog-business lifecycle deferred to spec 16 REQ-5 (POST <route de deploiement prevue>) + Podman socket mount for forge-api"
  },
  "feature_pending": "catalog_business",
  "tracking": "V1: routes/mcp-streamable-http/index.ts L370-377"
}

Conséquences pour votre intégration : ne programmez pas de déploiement par cette API aujourd'hui. Le rapport de scan Trivy et le SBOM par serveur ne sont pas servis par .../{id}/security (503). Le SBOM CycloneDX de la plateforme elle-même est public sur GET /.well-known/sbom. Les secrets d'un locataire se gèrent par /api/v1/credentials (voir le chapitre « Routes des ressources »).

Voir aussi

• Routes MCP : le transport par session qui exécute les mêmes outils
• Routes des ressources : identifiants, document stores et autres ressources du locataire par l'API
• Parcourir le catalogue de services et préparer un déploiement : parcours pas à pas de ces routes, avec leurs réponses réelles
• MCP et Orchestrateur : les pages de l'application qui présentent ce catalogue
• Connecteurs MCP : connecteurs décrits dans ce livre et statuts du catalogue

Routes des gateways et de la prédiction

Une gateway est un assistant conversationnel : un graphe de workflow (flow_data) rattaché à un espace de travail, qui peut être publié pour un usage public. Ce chapitre décrit les routes réelles sous /api/v1/gateways, les messages, la prédiction (envoi d'une question), les retours utilisateur, le « warm start » et les sondes de santé.

Convention : les corps de requête et de réponse des routes de ce chapitre sont du JSON en snake_case (sauf mention contraire). Une erreur a la forme {"error": {"code": "...", "message": "..."}}, sauf le dépassement de débit (429, corps vide : voir Swagger). Les listes sont des objets à clé nommée (par exemple {"gateways": [...], "total": N} pour GET /api/v1/gateways) ; le serveur n'ajoute pas d'enveloppe générique {data, meta}.

Gestion des gateways

Toutes ces routes exigent un jeton (Authorization: Bearer <token>) et sont cloisonnées par organisation : un espace de travail hors de votre périmètre est refusé. L'identifiant d'espace de travail (workspace_id) se lit par GET /api/v1/workspaces (réponse {"workspaces": [...], "total": N}, avec l'id de chaque espace). Parcours minimal pour exposer un assistant : POST /api/v1/gateways, puis POST /api/v1/gateways/{id}/publish, puis POST /api/v1/prediction/{id}. <hote-api> est défini dans Swagger.

POST /api/v1/gateways

Corps (structure CreateGatewayRequest) : name et workspace_id sont obligatoires ; flow_data est une chaîne JSON ; gateway_type, chatbot_config et deployed sont facultatifs.

curl -X POST "https://<hote-api>/api/v1/gateways" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Assistant comptabilite","workspace_id":"<uuid-espace>","flow_data":"{\"nodes\":[],\"edges\":[]}","deployed":false}'

Réponse 201 avec la gateway : id, name, type, deployed, is_public, category, workspace_id, created_at, updated_at, approval_required, et public_token / public_expires_at / flow_data / last_transfer quand ils existent (flow_data n'est pas renvoyé dans la liste). Le plafond du plan est appliqué à la création : au-delà du quota de gateways ou de workflows, la réponse est un refus de quota (402, ou 503 si le quota ne peut pas être évalué).

PUT /api/v1/gateways/{id} accepte, tous facultatifs : name, flow_data, deployed, is_public, chatbot_config, api_config, category et approval_required (supervision humaine par gateway).

Publication

curl -X POST "https://<hote-api>/api/v1/gateways/<gateway-id>/publish" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"expires_at":"2027-01-31T23:59:59Z"}'

Le corps JSON est attendu même sans expiration : envoyez {}. expires_at (RFC 3339) est facultatif ; une valeur mal formée est refusée plutôt qu'ignorée (400, code VALIDATION_ERROR). Pour une gateway dont le graphe désigne un patient (lien patient), l'expiration est obligatoire en pratique : sans expires_at elle vaut 30 jours, au-delà de 90 jours ou dans le passé la publication est refusée (constantes fixées dans le code). La réponse est la gateway à jour, avec son public_token.

Transfert, budget

POST .../transfer prend to_workspace_id (obligatoire), reason et transmission_note. POST /api/v1/gateways/transfer-batch prend from_workspace_id, to_workspace_id et, facultativement, gateway_ids, reason, transmission_note. PATCH .../budget prend {"monthly_limit": <entier>} ; 0 signifie illimité.

Historique des conversations

GET .../chat-messages prend chatId (la conversation) et order (ASC par défaut, ou DESC). GET .../chat-sessions accepte chatType mais ne filtre pas dessus : la plateforme n'enregistre pas le canal d'une conversation.

curl "https://<hote-api>/api/v1/gateways/<gateway-id>/chat-messages?chatId=conv-123&order=ASC" \
  -H "Authorization: Bearer <token>"

GET /api/v1/gateway-messages prend limit et offset et renvoie {"gateway_messages": [...], "total": N, "offset": ..., "limit": ...}. POST /api/v1/gateway-messages prend role, mcp_gateway_id, content, chat_type et chat_id (et session_id facultatif). Un message d'une gateway d'une autre organisation répond 403.

Prédiction : poser une question

POST /api/v1/prediction/{id}

{id} est l'identifiant de la gateway. Cette route sert le widget intégrable ; elle ne demande pas de jeton, mais la gateway doit être publiée. Corps : question (ou message), sessionId facultatif, streaming facultatif (accepté, mais la réponse est toujours consolidée en un seul bloc).

curl -X POST "https://<hote-api>/api/v1/prediction/<gateway-id>" \
  -H "Content-Type: application/json" \
  -d '{"question":"Quels sont les clients avec un chiffre d affaires superieur a 100k ?","sessionId":"conv-123"}'

Réponse (forme de la branche d'exécution d'outil) :

{
  "gateway_id": "<uuid>",
  "chat_id": "conv-123",
  "text": "Voici les clients...",
  "response": "Voici les clients...",
  "generated_by": { "...": "marquage IA" },
  "agent": {
    "tool": "<outil utilisé>",
    "module": "<module>",
    "resolution_path": "<chemin de résolution>",
    "confidence": 0.9
  }
}

Cas particuliers : 400 MISSING_QUESTION si ni question ni message ; 403 SECURITY_BLOCKED si le garde d'injection de prompt bloque l'entrée ; une demande de conseil clinique reçoit un refus rédigé avec refusal_reason. POST /api/v1/prediction (sans identifiant) répond 412 ID_REQUIRED. Le quota par défaut est de 20 requêtes par minute et par adresse IP sur le préfixe /api/v1/prediction (variable FORGE_RATE_LIMIT_PREDICTION_PER_MIN). Le limiteur compare le début du chemin : /api/v1/predictions et /api/v1/predictions/stream tombent dans le même seau.

POST /api/v1/predictions

Complétion directe, jeton obligatoire. Corps : prompt (obligatoire), system, model, max_tokens, temperature, session_id. Réponse : {"text", "model", "tokens", "latency_ms", "generated_by"}.

Retours utilisateur

Corps de création : message_id (uuid), gateway_id (uuid), chat_id, rating (thumbs_up, thumbs_down ou null) et content. Un autre rating répond 422 VALIDATION_FAILED.

Warm start