Hermes : les 32 outils MCP

1. Quoi ? — Définition et contexte

Un agent sans outils ne peut que parler. Ce qui rend Hermes utile, c’est le catalogue de 32 outils métier qu’il peut appeler pour lire et modifier l’état réel du système : projets Odoo, conteneurs Docker, métriques Prometheus, notes du vault Obsidian.

Ces outils ne vivent pas dans le conteneur de l’agent. Ils sont définis dans un workflow N8N (Hermes MCP Tools, 33 nodes, actif) qui les expose via un unique MCP Server Trigger protégé par Bearer. Le conteneur ne connaît qu’une URL et un token.

Les deux canaux MCP

Canal	Cible	Outils	Usage
n8n-tools	n8n:5678/mcp/hermes-tools	32 outils métier curés	Le flow normal, 99 % des appels
n8n-admin	n8n-mcp:3000/mcp	4 outils, filtrés sur 24 exposés	Diagnostic de workflows uniquement

Pourquoi filtrer le canal admin

Le serveur n8n-mcp expose 24 outils, dont n8n_delete_workflow et n8n_manage_credentials. Le brancher tel quel reviendrait à donner à l’agent les clés de toute l’automatisation pour lui permettre de lire un log d’exécution. La clause tools.include du fichier de config le réduit à quatre outils de lecture seule — n8n_list_workflows, n8n_get_workflow, n8n_executions, n8n_validate_workflow — et une règle du system prompt interdit de l’utiliser pour une action métier.

Architecture

---

2. Pourquoi ? — Enjeux et motivations

Pourquoi des outils curés plutôt qu’un accès direct ?

Il aurait été plus rapide de donner à l’agent un accès générique à l’API Odoo et de le laisser composer ses appels XML-RPC. Trois raisons de ne pas le faire.

Enjeu	Ce qu’apporte un outil dédié
Surface	Un outil ne fait qu’une chose. odoo_update_task ne peut pas supprimer un projet, quelle que soit la créativité du modèle
Schéma	Chaque paramètre a un nom, un type et une description. Le modèle n’a pas à deviner la forme d’un domaine Odoo
Point de contrôle	Un node N8N entre l’agent et la cible permet de valider, plafonner, échapper et journaliser avant exécution

Le coût est réel — chaque nouvel outil est un node à créer — mais il se paie une fois, et il rend le comportement de l’agent prévisible.

Pourquoi des gateways à entrées typées ?

Les outils non-Odoo ne pointent jamais directement sur les workflows existants. Chaque domaine passe par un wrapper qui définit ses propres entrées, puis délègue.

Sans wrapper, l’agent devrait connaître le contrat interne de Docker Actions ou du Telegram Content Pipeline — des workflows conçus pour d’autres appelants, dont la forme peut changer. Le wrapper découple : il donne à l’agent un schéma MCP propre et stable, et absorbe les évolutions internes.

---

3. Comment ? — Mise en œuvre technique

Le catalogue complet

Odoo — projets et tâches (10)

Outil	Rôle
odoo_list_projects	Liste id + nom des projets
odoo_create_project	Crée un projet (l’ORM crée le compte analytique associé)
odoo_update_project	Met à jour un champ (nom / description)
odoo_archive_project	Archive ou désarchive
odoo_list_task_stages	Étapes kanban d’un projet (id, nom, séquence, repliée)
odoo_move_task_stage	Déplace une tâche dans le kanban
odoo_list_tasks	Tâches d’un projet
odoo_get_task	Détail d’une tâche, description incluse
odoo_create_task	Crée une tâche
odoo_update_task	Met à jour un champ (nom / description / échéance)

Odoo — contacts (3) : odoo_search_contacts (recherche par nom, retourne coordonnées et adresse), odoo_create_contact, odoo_update_contact.

Odoo — CRM (6) : crm_list_stages (étapes du pipeline avec séquence et is_won), crm_list_leads, crm_create_lead (type=opportunity forcé pour que le lead atterrisse dans le pipeline), crm_update_lead, crm_move_stage, crm_delete_lead — sensible.

Odoo — timesheets (4) : timesheet_report (lignes depuis une date), timesheet_log_hours, timesheet_update, timesheet_delete — sensible.

Vault Obsidian (4) : vault_search (grep insensible à la casse, 3 correspondances par fichier, plafond 60 lignes), vault_list (fichiers suivis, plafond 300), vault_read (plafond 30 000 caractères, retourne un contentHash), vault_write (écriture confinée).

Infrastructure (5) : docker_read (status / logs / liste), docker_manage (start / stop / restart / update — sensible), monitoring_alerts, monitoring_query (PromQL instantané), content_generate (brouillon de note, article ou recherche).

Les six outils Plaud ont quitté ce catalogue

Jusqu’au 6 août 2026, six outils plaud_* (enregistrements vocaux, transcripts, notes IA) passaient par un gateway N8N et un community node non officiel, avec un token Bearer extrait du webapp qui expirait périodiquement. Plaud ayant publié son propre serveur MCP, ces outils sont désormais servis directement au conteneur (npx -y @plaud-ai/mcp@latest) : le gateway et sa maintenance de token disparaissent. Deux capacités restent sans équivalent officiel — le statut des traitements IA en cours et le téléchargement de l’audio brut vers Telegram.

Les quatre gateways

Gateway	Entrées	Délègue à
Docker	dockerStack, dockerAction	Docker Actions
Monitoring	mode (alerts / query), promql	SSH local → curl Prometheus 127.0.0.1:9090
Content	contentType, text, url	Telegram Content Pipeline
Vault	vaultAction, vaultQuery, vaultContent, vaultBaseHash	SSH local → git + grep sur ~/vaults/vps-vault

Prometheus n’écoute que sur le loopback du host : le gateway monitoring passe donc par SSH puis curl, comme le health check Docker. Le PromQL est échappé avant insertion dans la commande.

L’écriture confinée dans le vault

vault_write est le seul outil qui modifie durablement quelque chose hors d’Odoo. Sa validation se fait en JavaScript avant construction de la commande shell : liste blanche de préfixes (research/, inbox/), extension .md obligatoire, anti-traversal, contrôle des caractères, plafond de 150 000 octets — comptés en octets, pas en caractères.

Le point intéressant est le read-before-overwrite, sans état partagé : vault_read renvoie un contentHash (sha256 tronqué à 12 hexadécimaux), et écraser un fichier existant exige de repasser ce hash en Base_Hash. Sans hash, la réponse est __EXISTS__ ; si le fichier a changé depuis la lecture, __STALE_READ__.

Les erreurs ne renvoient jamais le hash courant

C’est délibéré. Si __STALE_READ__ retournait le hash à jour, le modèle n’aurait qu’à le recopier pour écraser un fichier qu’il n’a pas lu — le garde-fou deviendrait une formalité. L’erreur oblige à repasser par vault_read.

Contourner MAX_ARG_STRLEN

Le contenu transite en base64 par blocs de 64 Ko, une commande SSH par bloc vers un fichier temporaire, parce que Linux plafonne chaque argument de commande shell à 128 Ko (Argument list too long, constaté sur une note de 120 000 caractères). La commande finale vérifie la taille exacte du base64 avant décodage : un bloc perdu produit __WRITE_FAILED__, jamais un fichier corrompu commité. La séquence se termine par un commit et un push immédiat, ce qui propage la note vers les clients Obsidian.

Les erreurs structurées

Les gateways ne lèvent pas d’exception sur une entrée invalide : ils renvoient un marqueur que le formateur traduit en {success: false, error, hint}. __NOT_FOUND__, __BAD_PATH__, __BAD_ACTION__, __EMPTY_QUERY__, __EXISTS__, __STALE_READ__.

L’effet de bord est important : ces réponses ne déclenchent pas le Global Error Handler. Une faute de frappe de l’agent est une réponse métier, pas un incident d’infrastructure — elle repart directement dans la conversation avec un indice sur la correction à apporter.

Quatre pièges de la couche MCP N8N

Les paramètres $fromAI sont requis par défaut

Le MCP Server Trigger marque chaque paramètre $fromAI comme obligatoire. Rendre un champ optionnel demande de passer une valeur par défaut en quatrième argument : $fromAI('x', '...', 'string', ''). Sans ça, l’agent doit inventer une valeur pour chaque champ facultatif.

Les descriptions d'outils Odoo sont ignorées

Le trigger sert la description générique du wrapper odooTool (« Create an item in Odoo ») quelle que soit la toolDescription renseignée. Toute la sémantique repose donc sur le nom de l’outil et sur les descriptions $fromAI de chaque champ — d’où des noms explicites comme crm_move_stage plutôt que odoo_update_5.

Le catalogue est mis en cache par session MCP

Ajouter ou modifier un outil dans N8N ne suffit pas : le conteneur garde le catalogue pour la durée de la session. docker compose restart hermes est nécessaire après tout changement de schéma, sinon l’agent continue d’appeler l’ancienne signature.

Un sous-node désactivé fait exécuter le mauvais outil

Le plus vicieux, découvert en production le 7 août 2026 en retirant les six outils Plaud. Les avoir simplement désactivés a suffi à faire router 27 des 32 outils vers le mauvais node : docker_read exécutait odoo_create_contact et renvoyait « Contacts require a name », odoo_list_projects exécutait docker_manage.

En cause, getConnectedTools() côté N8N, qui associe chaque outil à son node source par index, en assemblant deux listes construites différemment — l’une filtre les nodes désactivés, l’autre les conserve. Un seul node désactivé décale tout ce qui suit. En mode queue, le processus principal résout bien l’outil par son nom, mais ne transmet au worker que le nom du node source, déjà faux.

La panne est silencieuse : tools/list reste correct, donc rien ne semble cassé jusqu’à ce qu’un outil renvoie l’erreur d’un autre domaine. Pour retirer un outil, il faut supprimer le node, jamais le désactiver.

Sécurité

Surface	Protection
Endpoint MCP	Bearer obligatoire — 403 sans token, vérifié en E2E
Depuis Internet	/mcp/* et /mcp-test/* renvoient 404 côté Caddy ; seul n8n:5678 en interne fonctionne
docker_manage	Whitelist d’actions dans Docker Actions ; security-stack non actionnable
Actions destructrices	docker_manage, crm_delete_lead, timesheet_delete exigent une confirmation explicite, imposée par le system prompt
Écriture vault	Préfixes en liste blanche, anti-traversal, read-before-overwrite

La confirmation repose sur le prompt, pas sur la plomberie

Il n’existe aucune chaîne d’approbation en aval de docker_manage sur ce chemin — contrairement au workflow d’approbation utilisé ailleurs. Le garde-fou est une règle du system prompt qui oblige l’agent à demander confirmation avant chaque appel. Ça fonctionne en pratique (vérifié en E2E : la confirmation est bien demandée avant un restart réel), mais c’est une garantie comportementale, pas technique. La vraie barrière reste la whitelist d’actions côté Docker Actions.

---

4. Et si ? — Perspectives et limites

Limites actuelles

Limite	Impact	Mitigation
employee_id figé à 1	timesheet_log_hours écrit toujours sur le même employé	Sans objet aujourd’hui, à paramétrer si l’équipe grandit
Redémarrage après chaque évolution	Toute modification de schéma impose un restart	Regrouper les changements d’outils
Pas d’approbation en aval	Les actions sensibles ne sont protégées que par le prompt	Whitelist côté Docker Actions ; chaîne d’approbation à câbler
Aucun sous-node désactivable	Désactiver un outil casse le routage de tous les suivants	Supprimer le node plutôt que le désactiver (voir le quatrième piège)

Scénarios d’évolution

Si les actions sensibles doivent être vraiment bloquantes :

• Réutiliser le MCP Confirmation Handler déjà en place pour CLI Ollama plutôt que d’en écrire un second.
• Le gateway posterait un webhook et attendrait le callback Telegram, comme le fait déjà cli-ollama.

Si le catalogue continue de grossir :

• 32 outils tiennent encore dans un prompt, mais chaque outil coûte des tokens à chaque tour.
• Piste : des toolsets activables par contexte, sur le modèle du /mcp par conversation du système conversationnel.

Si un outil doit écrire ailleurs que dans le vault :

• Le patron vault_write est réutilisable tel quel : liste blanche de préfixes, validation avant construction de commande, read-before-overwrite par hash.
• La partie coûteuse — le transfert chunké et la vérification d’intégrité — est déjà écrite.

Dépannage

# Le catalogue vu par l'agent
docker exec hermes hermes mcp test n8n-tools

# Tester l'endpoint directement (403 attendu sans token)
docker exec n8n sh -c 'curl -s -o /dev/null -w "%{http_code}\n" -X POST \
  http://n8n:5678/mcp/hermes-tools'

# Vérifier que l'endpoint reste fermé depuis l'extérieur (404 attendu)
curl -so /dev/null -w '%{http_code}\n' https://n8n.guigpap.com/mcp/hermes-tools

---

Pages liées

Hermes

• Hermes Agent — Le déploiement et son modèle de sécurité
• Skills — Les procédures qui exploitent ces outils
• Mémoire Mnemosyne — Les outils de mémoire, côté conteneur

Workflows

• Error Handler — Workflow d’erreur des gateways
• Docker Updates — Docker Actions, cible du gateway Docker
• Content Pipeline — Cible du gateway contenu, et le vault vps-vault

Référence

• Glossaire — MCP, Agent autonome