Hermify
Retour au blog
AI AgentsMCPTroubleshooting

Outils MCP de Hermes Agent absents : le fix rapide

Votre serveur MCP est configuré mais aucun outil n'apparaît en session. Cinq pannes silencieuses et le chemin de diagnostic pour chacune.

Par Hermify Team||6 min de lecture
Scène technique sombre avec une connexion MCP cassée et le texte MCP Not Loading

Vous avez ajouté un serveur MCP à ~/.hermes/config.yaml, redémarré la passerelle, puis demandé à Hermes de lister ses outils. Rien de nouveau. Pas d'erreur, pas d'avertissement, gateway.log muet. Ce billet est le chemin le plus court entre ce silence et un mcp_<serveur>_<outil> qui fonctionne dans votre session.

Cinq modes d'échec expliquent presque tous les cas signalés, et chacun se cache à un endroit différent. Bonne nouvelle : hermes mcp list, hermes mcp test et un seul flag de log vous diront en moins de deux minutes lequel des cinq vous concerne.

Pourquoi ces pannes silencieuses existent

La configuration MCP est la surface la moins bien loggée de Hermes. Quand le loader ne parvient pas à démarrer un serveur, à importer l'extra Python mcp, ou à parser le bloc mcp_servers, la panne est journalisée en DEBUG et ne remonte jamais dans gateway.log sur l'installation par défaut. Pour vous, on dirait que la config a été acceptée et que les outils n'existent simplement pas.

Le fix commence par la visibilité, avant tout le reste. Redémarrez Hermes en logging verbeux pour que le loader vous dise pourquoi il a abandonné :

hermes serve --verbose
# ou, si vous lancez via docker compose :
HERMES_LOG_LEVEL=DEBUG docker compose up

Relancez ensuite hermes mcp list. Si votre serveur apparaît dans la liste sans outils accrochés, la connexion tient mais la découverte a échoué. Si le serveur est absent, le loader ne l'a jamais enregistré. Cette bifurcation vous indique quel fix parmi ceux qui suivent s'applique.

Cause 1 : l'extra Python mcp n'est pas installé

Si vous avez compilé Hermes depuis les sources ou épinglé un tag précis, le paquet mcp est un extra optionnel qui n'est pas pris par l'install par défaut. Sans lui, chaque entrée sous mcp_servers est ignorée en silence. C'est la cause numéro un sur les installations sur mesure.

Réinstallez avec l'extra activé :

cd ~/.hermes/hermes-agent
uv pip install -e ".[mcp]"
hermes serve --verbose

Si la passerelle démarre et tente de joindre le serveur, il vous manquait le SDK. Si le log dit toujours mcp module not available, l'extra n'est pas installé dans l'interpréteur que Hermes exécute réellement : regardez hermes --version pour trouver le chemin du venv et relancez l'install dedans.

Cause 2 : votre indentation YAML est décalée d'un espace

YAML jette silencieusement tout bloc dont l'indentation ne colle pas à son parent. Une tabulation égarée, un - à la mauvaise profondeur, ou deux points sans guillemets dans une chaîne de commande font disparaître toute la map mcp_servers sans un mot.

La forme sûre : indentation à deux espaces, guillemets autour de toute chaîne contenant deux points, listes avec - :

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    enabled: true
  stripe:
    url: "https://mcp.stripe.com/v1/sse"
    enabled: true

Deux vérifs rapides : lancez python -c "import yaml; yaml.safe_load(open('$HOME/.hermes/config.yaml'))" pour confirmer que le fichier parse, puis hermes mcp list pour confirmer que les noms apparaissent. Si le fichier parse mais que le bloc est vide côté Hermes, l'indentation est mauvaise malgré une syntaxe légale.

Cause 3 : node ou npx manque sur l'hôte

La plupart des serveurs MCP de la communauté sont livrés en paquets npm et lancés avec npx -y @modelcontextprotocol/server-<nom>. Si l'hôte n'a pas Node.js dans PATH, le sous-processus meurt avant d'imprimer quoi que ce soit et Hermes note la panne en DEBUG seulement. C'est la cause la plus fréquente à l'intérieur des conteneurs Docker minimalistes.

Testez le lancement hors de Hermes d'abord :

node --version
npx --version
npx -y @modelcontextprotocol/server-filesystem /tmp

Si l'une des trois commandes échoue, installez Node.js dans l'environnement où Hermes tourne. Sous Docker, cela veut dire ajouter nodejs et npm à votre image ou partir d'une base qui les contient déjà. Hermes ne peut pas lancer un binaire Node qui n'existe pas.

Cause 4 : le serveur se connecte mais ses outils ne remontent pas dans la session

Vous voyez le serveur dans hermes mcp list, hermes mcp test <serveur> découvre ses outils, et pourtant rien de nouveau n'est appelable dans la session. C'est la panne documentée dans l'issue #51587 et l'issue #71736 : la découverte a fonctionné, mais les outils n'ont jamais été injectés dans le toolset de la session.

Les contournements fiables :

  • Lancez /reload-mcp dans votre session Hermes, ou redémarrez complètement la passerelle. Certains builds peuplent le toolset une seule fois au boot et loupent les serveurs qui remontent tard.
  • Vérifiez le champ enabled_toolsets de la session. S'il est trop restreint (la session ACP hardcode ["hermes-acp"], par exemple), les outils MCP sont exclus par conception et il faut ouvrir le toolset.
  • Confirmez que votre provider supporte réellement l'usage d'outils. Les modèles Ollama doivent être lancés avec un template d'outil compatible Hermes, et les anciens modèles locaux annoncent des outils découverts mais ne les appellent jamais.

Cause 5 : votre provider abandonne les tool calls en silence

Même avec le serveur debout et les outils enregistrés, certains providers retirent le payload d'outil avant que le modèle le voie. Le symptôme est identique à un MCP cassé : l'outil existe mais rien ne se passe quand vous le demandez.

Vérif de deux minutes : basculez la session sur un provider connu pour son tool calling (n'importe quel modèle récent d'Anthropic, OpenAI ou Groq) et posez la même question. Si l'outil se déclenche là, c'est votre provider ou votre choix de modèle, pas MCP. S'il ne se déclenche toujours pas, revenez à la Cause 4.

Le chemin de diagnostic, dans l'ordre

Exécutez ceci dans cet ordre et arrêtez-vous dès que quelque chose change ce que vous voyez :

  1. hermes serve --verbose - les pannes sortent enfin sur stdout.
  2. python -c "import yaml; yaml.safe_load(open('$HOME/.hermes/config.yaml'))" - confirme que le fichier parse au minimum.
  3. hermes mcp list - montre ce que le loader a accepté.
  4. hermes mcp test <serveur> - montre si connexion et découverte tiennent.
  5. hermes mcp health - un snapshot par serveur quand vous devez passer la main.
  6. /reload-mcp dans votre session, ou un redémarrage complet de la passerelle.
  7. Changez de provider pendant deux minutes pour un A/B.

Pour un tour complet de la surface de diagnostic, le guide de debugging et d'observabilité de Hermes couvre gateway.log, le tracing par outil et comment tailer tout ça proprement. Si vous montez encore votre premier serveur MCP, le guide de setup MCP parcourt la forme du fichier de config avant qu'aucune des pannes ci-dessus ne devienne possible.

Sautez toute cette surface

Chaque panne de ce billet vient d'un décalage entre Hermes et son hôte : un extra Python absent, un binaire Node absent, une permission mal posée sur le fichier de config, un bug d'ordre de boot de session. Hermify prend toute cette surface en charge pour vous.

Démarrez avec Hermify pour lancer un Hermes Agent géré sur Telegram, avec MCP déjà câblé, l'extra mcp installé, npx disponible sur l'hôte et le reload à la modification de la config qui marche d'origine. Vous gardez votre config MCP, vous gardez votre mémoire, et vous arrêtez de diagnostiquer de l'indentation YAML un mardi soir.

Sources

Lancez votre propre agent Hermes

Apportez votre clé API, connectez Telegram et obtenez un agent IA auto-améliorant opérationnel en 60 secondes.

Commencer