Hermes Agent MCP : connecter des outils externes
Connectez Hermes Agent à un serveur MCP, filtrez les outils, gérez transport et secrets, puis validez l'intégration en production.
Introduction
Hermes Agent MCP est la voie officielle pour brancher des outils externes — GitHub, Linear, fichiers, API internes — sans réécrire un outil natif pour chaque service. Ce tutoriel explique comment connecter un serveur MCP à Hermes Agent de bout en bout : choisir entre catalogue, stdio et HTTP, écrire la configuration, filtrer les outils, valider par un appel réel et diagnostiquer les pannes. Il est utile dès que la capacité vit ailleurs qu'au cœur de Hermes et que vous voulez la tester avant production. En revanche, pour un appel HTTP à une route GET stable, restez sur une approche plus simple — MCP est une couche qui ne se justifie que si la liste d'outils évolue ou si plusieurs agents partagent le serveur.
Résumé rapide
| Étape | Commande ou fichier | Ce que vous validez |
|---|---|---|
| État courant | hermes mcp list | serveurs installés, statut (activé/désactivé) |
| Catalogue | hermes mcp catalog ou hermes mcp install <nom> | entrée Nous-approved dans optional-mcps/ |
| Serveur manuel | hermes mcp add NAME --command "..." ou --url "..." | ajout dans ~/.hermes/config.yaml sous mcp_servers |
| Authentification | env: (stdio) ou headers: (HTTP) + ~/.hermes/.env | secret hors config.yaml |
| Filtrage | mcp_servers.<nom>.tools.include / tools.exclude | surface minimale exposée |
| Test | hermes mcp test <nom> puis lecture en session ou via /reload-mcp | appel attribué et réponse bornée |
| Mode serveur | hermes mcp serve | exposition de Hermes (parcours secondaire) |
Ce que MCP ajoute à Hermes Agent
Le Model Context Protocol (MCP) est un protocole standardisé qui permet à un agent comme Hermes Agent MCP de dialoguer avec des serveurs d'outils externes. Hermes joue le rôle de client : il interroge le serveur au démarrage, récupère la liste d'outils via list_tools(), et les enregistre sous la forme mcp_<serveur>_<outil> — par exemple mcp_filesystem_read_file. Cette surface s'ajoute aux outils natifs (terminal, read_file, web_extract) et aux skills procéduraux sans les remplacer.
MCP devient pertinent dès que la capacité existe ailleurs, évolue souvent ou doit être partagée entre plusieurs agents. Trois signaux : la liste d'outils change avec le temps (Linear, GitHub, Stripe), plusieurs agents appellent le même serveur avec les mêmes credentials, ou le fournisseur expose un serveur MCP officiel. Point de vigilance : un serveur MCP peut exécuter du code et accéder à des systèmes tiers selon son périmètre — d'où le filtrage et le test avant production.
Hermes Agent (client)
└─ mcp_servers.fs-demo → @modelcontextprotocol/server-filesystem
(commande: npx, args: [..., "/démo"])
└─ outils: read_file, list_directory…
Choisir, installer, filtrer et tester un serveur MCP
Catalogue, stdio ou HTTP
Trois voies pour brancher un serveur MCP. Le catalogue officiel : les entrées vivent dans optional-mcps/ du dépôt NousResearch/hermes-agent, leur présence vaut approbation par l'équipe Nous (manifest_version pinné). Désactivées par défaut. Le stdio local : Hermes lance le serveur comme sous-processus et dialogue en stdin/stdout — mode dominant pour les serveurs npx ou uvx. Le HTTP distant : un endpoint URL, des en-têtes, éventuellement de l'OAuth — adapté aux SaaS officiels ou aux services auto-hébergés. Pour un OAuth hébergé (Figma, Linear, Stripe), comptez sur auth: oauth ; pour un bearer statique, sur un en-tête Authorization explicite. Le pont n8n historique a été retiré : migrez vers hermes mcp install n8n-official (URL en /mcp-server/http).
Installer depuis le catalogue
Trois commandes couvrent 90 % des cas. hermes mcp catalog liste les entrées en texte brut, hermes mcp ouvre le picker interactif, hermes mcp install <nom> installe sans interaction. Après l'installation, Hermes sonde le serveur pour lister ses outils et affiche une checklist pré-cochée (sélection précédente ou défauts du manifeste). Pour les serveurs à clé d'API, la valeur atterrit dans ~/.hermes/.env ; pour les OAuth tiers, hermes auth <provider> est appelé si nécessaire.
Ajouter manuellement un serveur
Pour un serveur absent du catalogue, deux chemins. La voie CLI :
hermes mcp add fs-demo --command "npx" \
--args "-y" "@modelcontextprotocol/server-filesystem" "/home/<utilisateur>/hermes-fs-demo"
La voie déclarative : éditer ~/.hermes/config.yaml sous mcp_servers. Pour un serveur stdio :
mcp_servers:
filesystem-demo:
command: "npx"
args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp/hermes-fs-demo"]
timeout: 30
Pour un serveur HTTP distant avec bearer statique :
mcp_servers:
api-interne-demo:
url: "https://api.example.internal/mcp"
headers:
Authorization: "Bearer ${API_INTERNE_TOKEN}"
timeout: 180
${API_INTERNE_TOKEN} se définit dans ~/.hermes/.env, jamais dans config.yaml. Pour un OAuth hébergé, remplacez headers par auth: oauth et laissez Hermes gérer PKCE, tokens et refresh dans ~/.hermes/mcp-tokens/<serveur>.json. Hermes applique un filtrage d'environnement pour les serveurs stdio : seules PATH, HOME, USER, LANG, LC_ALL, TERM, SHELL, TMPDIR et XDG_* sont héritées par défaut. Sous Docker ou WSL, le système de fichiers vu par le serveur n'est pas celui de votre session hôte : le répertoire passé en argument doit exister et être lisible par l'utilisateur sous lequel tourne Hermes.
Filtrer les outils et borner les permissions
Trois leviers réduisent la surface d'attaque. Le premier : mcp_servers.<nom>.tools.include, une allowlist explicite. Le second : mcp_servers.<nom>.tools.exclude, une blocklist pour les serveurs à très grande surface (Cloudflare expose ~3 300 outils OpenAPI — déclarez tools.default_excluded via le manifeste). Le troisième : la séparation des profils — un profil personnel et un profil automatisé n'ont aucune raison de partager les mêmes serveurs. include/exclude acceptent aussi des globs (*, ?, [...]) pour les serveurs qui exposent des milliers d'outils. Si vous filtrez tous les outils, Hermes ne crée pas de toolset MCP vide pour ce serveur.
Tester l'intégration de bout en bout
Trois commandes suffisent pour valider un serveur. hermes mcp list confirme que le serveur est installé et non filtré. hermes mcp test <nom> vérifie le démarrage, la négociation MCP (initialize) et la découverte d'outils. Dans une session neuve (hermes chat) ou après un changement via /reload-mcp, exécutez une opération de lecture sans effet de bord et vérifiez la réponse source.
L'acceptation ne porte pas sur « connected » ni sur mcp test seul. Elle porte sur un appel d'outil réussi, attribuable et borné : l'agent a bien invoqué le bon outil MCP, le serveur a renvoyé une réponse cohérente, et la réponse reste dans le périmètre attendu. Ajoutez un test négatif : outil exclu doit échouer proprement, secret absent doit lever une erreur claire, requête hors périmètre doit être refusée.
Diagnostiquer un serveur invisible ou muet
| Symptôme | Cause probable | Premier geste |
|---|---|---|
Serveur absent de mcp list | Entrée non installée ou désactivée | hermes mcp catalog puis install |
| Serveur sans outil | PATH/URL, secret ou filtre trop large | which, curl -I, hermes mcp configure <nom> |
| Réponse vide en stdio | stdout pollué par des logs serveur | Rediriger les logs vers stderr |
| 401 / token invalide en HTTP | Secret absent ou expiré | Vérifier ~/.hermes/.env, hermes mcp login <nom> |
| Délai ou timeout en HTTP | Proxy, DNS, firewall | Tester depuis la machine Hermes, vérifier NO_PROXY |
Pour stdio, un serveur qui écrit ses logs sur stdout casse la session ; pour HTTP, l'erreur vient presque toujours d'une URL ou d'un secret (relancer via hermes mcp login <nom>). Pour n8n, l'URL doit se terminer par /mcp-server/http, pas l'URL d'éditeur.
Exposer Hermes comme serveur MCP
hermes mcp serve lance Hermes lui-même comme serveur MCP pour qu'un client externe consomme ses outils — parcours secondaire qui ouvre les canaux configurés à un tiers. Limitez-vous aux outils de lecture ou de messagerie, et n'exposez jamais un shell, un accès filesystem ou un provider OAuth sans couche d'authentification dédiée. La liste des outils évolue vite ; référez-vous à la documentation officielle de votre version.
{
"mcpServers": {
"hermes": {
"url": "http://localhost:8787/mcp",
"transport": "http"
}
}
}
Exemple concret : accès contrôlé à un dépôt
Déroulons un cas réel minimal : Hermes Agent MCP doit pouvoir lister et lire des fichiers dans un dossier de démonstration, sans écrire ailleurs ni sortir du périmètre. Créez le dossier :
mkdir -p ~/hermes-fs-demo
echo "Premier fichier" > ~/hermes-fs-demo/notes.md
echo "Deuxième fichier" > ~/hermes-fs-demo/rapport.md
Installez le serveur filesystem (catalogue ou déclaratif) en limitant la racine à ~/hermes-fs-demo et en n'autorisant que la lecture :
mcp_servers:
fs-demo:
command: "npx"
args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/<utilisateur>/hermes-fs-demo"]
tools:
include: ["read_file", "list_directory"]
Ouvrez une session (hermes chat), puis exécutez deux requêtes : « Liste les fichiers de ~/hermes-fs-demo » puis « Lis notes.md ». Vérifiez que le serveur ne renvoie que des chemins sous ~/hermes-fs-demo — si vous voyez /etc ou ~/.ssh/, désinstallez immédiatement (hermes mcp remove fs-demo). Testez ensuite un outil non inclus : appelez une écriture et constatez qu'elle est refusée. Désactivez ou désinstallez le serveur quand vous ne l'utilisez plus, et renouvelez le token à chaque rotation de poste. Cet exemple tient en deux commandes — mcp_filesystem_list_directory puis mcp_filesystem_read_file — et prouve trois choses : le transport fonctionne, le filtrage limite la surface, et le serveur reste dans son répertoire racine.
Bonnes pratiques
Inspectez la source de tout serveur avant installation, même issu du catalogue officiel — lisez le manifest.yaml (champs source:, install.bootstrap:, transport.command:). Quand c'est possible, pinnez la version du paquet (@modelcontextprotocol/server-filesystem@1.2.3) pour éviter qu'une mise à jour silencieuse ajoute des outils non sollicités. Réduisez la liste d'outils activés à ce qui sert vraiment, réévaluez-la à chaque mise à jour via hermes mcp configure <nom>. Désactivez ou désinstallez les serveurs inutilisés : un serveur présent dans la config mais jamais invoqué est un vecteur d'attaque dormant.
Gardez un propriétaire par serveur, un inventaire daté des accès, et un test de non-régression après chaque changement de version — un script qui appelle hermes mcp test <nom> sur chaque serveur configuré suffit. Séparez les profils : un cron de production n'utilise pas la même instance Hermes ni les mêmes clés qu'un usage exploratoire (hermes --profile prod vs hermes --profile dev). Pour la mémoire de long terme et la réutilisation des procédures de setup, mesurez le coût LLM d'une reconfiguration à chaque nouvelle session — c'est précisément ce que la mémoire Hermes Agent doit résoudre. Gardez en tête que MCP est un moyen parmi d'autres : pour un appel HTTP simple et stable, restez sur une route documentée et un outil natif.
Questions fréquentes
Qu'est-ce que MCP pour Hermes Agent ?
MCP (Model Context Protocol) est un protocole standardisé qui permet à Hermes Agent de dialoguer avec des serveurs d'outils externes. Hermes joue le rôle de client MCP, découvre la liste d'outils au démarrage et les expose sous la forme mcp_<serveur>_<outil>. Pour un appel HTTP stable, un outil natif reste plus sobre.
Comment installer un serveur MCP Hermes Agent ?
Parcourez le catalogue officiel avec hermes mcp catalog, puis installez une entrée avec hermes mcp install <nom>. Pour un serveur absent du catalogue, déclarez-le dans ~/.hermes/config.yaml sous mcp_servers, ou utilisez hermes mcp add <nom> --command "..." (stdio) ou --url "..." (HTTP). Une session neuve ou /reload-mcp prend la config en compte.
Quels transports et authentifications sont supportés ?
Hermes gère les serveurs stdio locaux (stdin/stdout, npx/uvx/binaire) et les serveurs HTTP distants (URL + en-têtes, OAuth 2.1 ou bearer). Les OAuth tiers comme Figma ou Linear passent par auth: oauth ; les bearers statiques par headers: { Authorization: "Bearer ${TOKEN}" }. Les clés API vivent dans ~/.hermes/.env, jamais dans config.yaml.
Comment limiter les outils MCP Hermes exposés ?
Utilisez mcp_servers.<nom>.tools.include pour une allowlist explicite, ou tools.exclude pour une blocklist quand le serveur expose une surface très large. Les deux acceptent des globs (*, ?, [...]) pour les serveurs à milliers d'outils. En complément, séparez les profils : personnel et automatisé ne partagent pas les mêmes serveurs.
Comment diagnostiquer un serveur MCP qui ne répond pas ?
Commencez par hermes mcp list et hermes mcp test <nom>. Vérifiez le transport (PATH ou URL), l'authentification (~/.hermes/.env, hermes mcp login <nom> pour OAuth), puis le filtrage (hermes mcp configure <nom>). En stdio, redirigez les logs serveur vers stderr s'ils polluent stdout ; en HTTP, contrôlez HTTPS_PROXY et NO_PROXY.
Articles liés
Vos outils externes sont désormais branchés, filtrés et testés. Pour décider ce qui mérite d'être conservé durablement entre les sessions, l'étape logique est la configuration de la mémoire Hermes — sinon le contexte utile sera reconstruit à chaque coût. Un rappel : un serveur MCP ne remplace ni un skill procédural ni un outil natif quand la capacité est spécifique à Hermes.
Restez informé sur les agents IA
Nouveaux tutoriels, comparatifs et guides pratiques directement dans votre boîte mail.