Outils et MCP dans Hermes Agent

Introduction

Hermes Agent est un framework agentique qui interagit avec le monde via des outils: navigation web, execution de commandes shell, lecture et ecriture de fichiers, generation d'images, et bien plus. Cette page documente l'ensemble du systeme d'outillage: les outils integres, leur organisation en toolsets, le mecanisme de chargement differe, et l'integration MCP (Model Context Protocol) qui permet de connecter des serveurs d'outils externes.

Au total, Hermes Agent embarque environ 81 outils natifs repartis dans plus de 30 toolsets. A cela s'ajoutent les outils decouverts dynamiquement via MCP, qui apparaissent avec le prefixe mcp__<serveur>__.

Les outils integres: un apercu

Hermes Agent fournit des outils couvrant l'ensemble des taches qu'un agent autonome peut rencontrer. Voici les grandes familles:

Chaque outil appartient a exactement un toolset. Les toolsets composites (comme coding ou debugging) regroupent plusieurs toolsets de base pour un scenario donne. Les toolsets de plateforme (comme hermes-cli ou hermes-telegram) definissent la configuration complete pour un contexte de deploiement.

Questions couvertes

q-081: Quels outils sont inclus dans Hermes Agent ?

Hermes Agent inclut environ 81 outils natifs (au commit b4f8c491), repartis en plusieurs categories:

Outils de fichier (file): read_file, write_file, patch, search_files. Ces quatre outils couvrent la lecture avec pagination, l'ecriture avec creation automatique des repertoires parents, l'edition ciblee avec fuzzy matching, et la recherche rapide via ripgrep.

Outils de terminal (terminal): terminal pour les commandes shell (foreground et background), et process pour gerer les processus en arriere-plan (poll, wait, kill, send). Les sessions desktop ajoutent read_terminal, close_terminal, open_preview et focus_pane.

Outils web (web, search, browser): web_search et web_extract pour la recherche et l'extraction de contenu. Le toolset browser fournit 10 outils d'automatisation: browser_navigate, browser_click, browser_type, browser_snapshot, browser_scroll, browser_vision, browser_console, browser_back, browser_press, browser_get_images. Deux outils CDP (browser_cdp, browser_dialog) sont actives uniquement quand un endpoint Chrome DevTools Protocol est disponible.

Outils de code (code_execution): execute_code permet d'executer des scripts Python avec acces programme aux outils Hermes.

Outils de vision et media: vision_analyze (analyse d'images), image_generate (generation texte-vers-image et image-vers-image), video_analyze, video_generate, text_to_speech (synthese vocale).

Outils de memoire et contexte: memory (memoire persistante inter-sessions), session_search (recherche dans l'historique des conversations), skill_view, skill_manage, skills_list (gestion des skills).

Outils de planification: todo (liste de taches intra-session), clarify (poser des questions a l'utilisateur), cronjob (taches planifiees).

Outils de delegation: delegate_task (sous-agents isoles), et 12 outils kanban (kanban_create, kanban_complete, kanban_list, kanban_block, etc.) pour la coordination multi-agents.

Integrations de service: 7 outils Spotify, 4 outils Home Assistant, 2 outils Discord, 5 outils Feishu, 5 outils Yuanbao, et x_search pour X/Twitter.

Outils de bureau: computer_use pour le controle du bureau via cua-driver.

La liste complete et les parametres de chaque outil sont documentes dans la reference des outils.

q-082: Comment activer ou desactiver un toolset Hermes Agent ?

Trois methodes complementaires:

1. Interface interactive (curses)

hermes tools

Cette commande ouvre une interface en mode texte ou vous pouvez activer/desactiver chaque toolset par plateforme. Les modifications sont persistees dans config.yaml.

2. Commandes en session

Dans une session Hermes active:

/tools list              # liste les toolsets et leur etat
/tools disable browser   # desactive le toolset browser
/tools enable homeassistant  # active le toolset homeassistant

Les changements prennent effet au prochain /reset (nouvelle session), jamais en milieu de conversation, pour preserver le cache de prompt.

3. Configuration dans config.yaml

toolsets:
  - hermes-cli

agent:
  disabled_toolsets:
    - browser

Ou en ligne de commande pour une invocation unique:

hermes chat --toolsets "hermes-cli,web,file"
hermes chat --toolsets "debugging"     # composite: file + terminal + web
hermes chat --toolsets "all"           # tous les toolsets

Niveau fin: hermes tools permet aussi de desactiver des outils individuels (plus fin que le toolset). Un outil desactive individuellement est filtre meme si son toolset est active.

Important: les toolsets kanban et certains outils a acces conditionnel (browser, computer_use, code_execution, Home Assistant, cronjob) ne sont pas actives par le wildcard all/*. kanban doit etre explicitement liste, et les outils conditionnels apparaissent seulement quand leur prerequis (backend, credentials) est configure.

q-083: Comment fonctionne le chargement differe des outils ?

Hermes Agent utilise un mecanisme de chargement differe (deferred loading) pour les outils qui ne sont pas necessaires dans toutes les sessions. Ce systeme fonctionne en deux etapes:

1. Decouverte au demarrage

Au lancement, Hermes charge les outils des toolsets actifs. Pour les outils a chargement differe, seul leur nom et une courte description sont injectes dans le prompt systeme, pas leur schema complet. Cela reduit la taille du prompt et preserve le cache.

2. Chargement a la demande

Quand l'agent a besoin d'un outil differe, il utilise tool_search pour le trouver par mots-cles, puis tool_describe pour charger son schema JSON complet, et enfin tool_call pour l'invoquer. Ce mecanisme en trois etapes evite de saturer le contexte avec des schemas d'outils rarement utilises.

Les outils concernes par le chargement differe incluent notamment les outils de memoire agent (mcp__agentmemory__*) et d'autres outils specialises. Les outils du coeur (file, terminal, web, browser) sont toujours charges directement.

Cas particulier des outils MCP: les outils decouverts via MCP sont egalement charges au demarrage, mais leur decouverte elle-meme est asynchrone. Hermes lance la connexion a chaque serveur MCP dans une boucle d'evenements dediee, decouvre les outils disponibles, et les enregistre. Si un serveur MCP ne repond pas au demarrage, ses outils ne sont pas enregistres, mais le reste de l'agent fonctionne normalement.

q-084: Comment connecter un serveur MCP stdio a Hermes Agent ?

Un serveur MCP stdio s'execute comme un sous-processus local et communique via stdin/stdout. La configuration se fait dans ~/.hermes/config.yaml sous la cle mcp_servers:

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    timeout: 30

Champs obligatoires:

• command: l'executable a lancer (npx, uvx, ou tout binaire sur le PATH)
• args: les arguments passes a la commande

Champs optionnels:

• env: variables d'environnement supplementaires pour le sous-processus (ex: GITHUB_PERSONAL_ACCESS_TOKEN)
• timeout: timeout par appel d'outil en secondes (defaut: 120)
• connect_timeout: timeout de connexion initiale en secondes (defaut: 60)
• idle_timeout_seconds: recycler le serveur apres N secondes d'inactivite (defaut: 0 = jamais)
• max_lifetime_seconds: recycler le serveur apres N secondes d'age total (defaut: 0 = jamais)

Exemple complet avec authentification:

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxxxxxxxxxx"
    timeout: 60

Securite: Hermes ne transmet PAS l'integralite de votre environnement shell au sous-processus MCP. Seules les variables de base (PATH, HOME, USER, LANG, TERM, etc.) et les variables explicitement declarees dans env sont transmises. Cela empeche les fuites accidentelles de secrets.

Recyclage des serveurs lourds: pour les serveurs qui gardent un processus lourd en memoire (ex: Playwright avec Chromium), utilisez idle_timeout_seconds et max_lifetime_seconds pour les recycler automatiquement:

mcp_servers:
  playwright:
    command: "npx"
    args: ["-y", "@playwright/mcp@latest", "--headless"]
    idle_timeout_seconds: 900
    max_lifetime_seconds: 86400

Apres configuration, redemarrez Hermes ou utilisez /reload-mcp en session.

q-085: Comment connecter un serveur MCP HTTP a Hermes Agent ?

Un serveur MCP HTTP est un endpoint distant auquel Hermes se connecte directement, sans lancer de sous-processus local.

mcp_servers:
  company_api:
    url: "https://mcp.internal.example.com/mcp"
    headers:
      Authorization: "Bearer sk-xxxxxxxxxxxxxxxxxxxx"
    timeout: 180
    connect_timeout: 30

Champs obligatoires:

• url: l'URL du serveur MCP

Champs optionnels:

• headers: en-tetes HTTP envoyes avec chaque requete (authentification, etc.)
• timeout: timeout par appel d'outil (defaut: 120)
• connect_timeout: timeout de connexion initiale (defaut: 60)
• client_cert / client_key: certificats client pour mTLS
• auth: oauth: pour les serveurs necessitant OAuth 2.1 (voir q-086)

mTLS (mutual TLS): pour les serveurs qui exigent un certificat client:

mcp_servers:
  internal_api:
    url: "https://mcp.internal.example.com/mcp"
    client_cert: "~/.certs/mcp-client.pem"

Trois formats sont acceptes: un chemin PEM combine, un tuple [cert, key], ou un tuple [cert, key, password] pour les cles chiffrees.

Note importante: un serveur MCP doit avoir soit command (stdio) soit url (HTTP), pas les deux.

q-086: Comment gerer OAuth pour un serveur MCP distant ?

Hermes Agent integre nativement OAuth 2.1 pour les serveurs MCP distants. Le flux complet est gere automatiquement: decouverte de la configuration OAuth du serveur, enregistrement dynamique du client (DCR), PKCE, echange de code, rafraichissement des tokens, et re-authentification.

Configuration minimale:

mcp_servers:
  linear:
    url: "https://mcp.linear.app/mcp"
    auth: oauth

Au premier lancement, Hermes affiche une URL d'autorisation, ouvre votre navigateur si possible, et attend le callback OAuth sur un port loopback local. Les tokens sont stockes dans ~/.hermes/mcp-tokens/<serveur>.json avec les permissions 0o600.

Hotes distants / headless: quand Hermes tourne sur une machine differente de votre navigateur, deux options:

1. Paste-back: Hermes affiche "Or paste the redirect URL here..." a cote de l'URL d'autorisation. Ouvrez l'URL dans votre navigateur, approuvez, copiez l'URL complete de redirection, et collez-la dans le terminal.
2. SSH port forward: ssh -N -L <port>:127.0.0.1:<port> user@host dans un terminal separe.

Redirection proxy: pour les configurations avec un endpoint HTTPS public:

mcp_servers:
  myserver:
    url: "https://mcp.example.com/mcp"
    auth: oauth
    oauth:
      redirect_port: 8765
      redirect_uri: "https://oauth.example.ts.net/callback"

Serveurs sans DCR (Google Drive, Atlantian): certains serveurs rejettent l'enregistrement dynamique. Creez un client OAuth dans la console du fournisseur et ajoutez les identifiants:

mcp_servers:
  googledrive:
    url: "https://drivemcp.googleapis.com/mcp/v1"
    auth: oauth
    oauth:
      client_id: "<votre-client-id>"
      client_secret: "<votre-client-secret>"

Puis lancez hermes mcp login googledrive.

Commandes utiles:

hermes mcp login <serveur>    # lancer ou refaire le flux OAuth
hermes mcp configure <serveur> # reconfigurer un serveur

Piege: si vous editez config.yaml depuis une session Hermes active, l'auto-rechargement a un timeout de 30s, insuffisant pour un flux OAuth interactif. Ajoutez l'entree puis lancez hermes mcp login <serveur> depuis un terminal frais.

q-087: Comment filtrer les outils exposes par un serveur MCP ?

Hermes offre un filtrage fin par serveur MCP, avec trois mecanismes:

1. Whitelist (include): seuls les outils listes sont enregistres.

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
    tools:
      include: [create_issue, list_issues, search_code]

2. Blacklist (exclude): tous les outils sont enregistres sauf ceux listes.

mcp_servers:
  stripe:
    url: "https://mcp.stripe.com"
    tools:
      exclude: [delete_customer, refund_payment]

3. Motifs glob (fnmatch): pour les serveurs exposesant des centaines d'outils (ex: Cloudflare, ~3300 outils), les motifs glob permettent d'exclure des familles entieres:

mcp_servers:
  cloudflare:
    url: "https://mcp.cloudflare.com/mcp?codemode=false"
    auth: oauth
    tools:
      exclude: ["*_radar_*", "*_accounts_dlp_*", "*_zones_web3_*"]

Les entrees sans metacaracteres (*, ?, [) correspondent exactement: docs exclut uniquement l'outil nomme docs, jamais docs_search.

Regle de precedence: si include et exclude sont tous deux presents, include gagne.

Filtrage des utilitaires MCP: vous pouvez aussi desactiver les wrappers de ressources et de prompts ajoutes par Hermes:

mcp_servers:
  docs:
    url: "https://mcp.docs.example.com"
    tools:
      prompts: false
      resources: false

Desactiver un serveur entier: utilisez enabled: false pour qu'Hermes ignore completement le serveur sans tenter de connexion.

mcp_servers:
  legacy:
    url: "https://mcp.legacy.internal"
    enabled: false

Selection interactive a l'installation: le catalogue MCP (hermes mcp install) presente une checklist des outils exposes par le serveur. Vous cochez ceux que vous voulez exposer, et seuls ceux-la sont ecrits dans tools.include.

q-088: Comment diagnostiquer un serveur MCP qui ne repond pas ?

Symptomes courants:

• Message "Failed to connect to MCP server 'X'" au demarrage
• Les outils MCP n'apparaissent pas dans la liste des outils disponibles
• Timeout lors de l'appel d'un outil MCP

Etape 1: Verifier les prerequis

# Le package mcp Python est-il installe?
pip list | grep mcp

# Node.js et npx pour les serveurs stdio
node --version
npx --version

# uvx pour les serveurs Python
uvx --version

Si le package mcp est absent, installez-le: pip install mcp.

Etape 2: Verifier la configuration

hermes doctor

Cette commande detecte les erreurs de syntaxe YAML, les cles inconnues, et les problemes de configuration MCP.

Etape 3: Verifier les logs de demarrage

Au lancement de Hermes, les messages de connexion MCP apparaissent dans les logs. Cherchez:

• "MCP SDK not available -- skipping MCP tool discovery" (package mcp absent)
• "No MCP servers configured" (cle mcp_servers absente ou vide)
• "Failed to connect to MCP server 'X'" (serveur injoignable)

Etape 4: Tester la commande manuellement

Pour un serveur stdio, testez si la commande fonctionne en dehors de Hermes:

npx -y @modelcontextprotocol/server-github --help

Pour un serveur HTTP, verifiez l'accessibilite:

curl -I https://mcp.example.com/mcp

Etape 5: Recharger la configuration MCP

En session Hermes:

/reload-mcp

Cela recharge les serveurs MCP depuis config.yaml et rafraichit la liste d'outils.

Etape 6: Verifier le timeout

Si le serveur est lent a demarrer, augmentez connect_timeout:

mcp_servers:
  mon_serveur:
    command: "npx"
    args: ["-y", "mon-package-lourd"]
    connect_timeout: 120

Causes frequentes:

• Commande introuvable: le binaire (npx, uvx) n'est pas sur le PATH
• Package npm absent: pour les serveurs npx, le package peut ne pas exister ou necessiter -y dans args
• Timeout: le serveur met trop de temps a demarrer. Augmentez connect_timeout
• Conflit de port: pour les serveurs HTTP, l'URL peut etre injoignable
• Version mcp obsoletes: pour les serveurs HTTP, pip install --upgrade mcp
• OAuth non complete: pour les serveurs avec auth: oauth, lancez hermes mcp login <serveur>

Reconnexion automatique: Hermes tente jusqu'a 5 reconnexions avec backoff exponentiel (1s, 2s, 4s, 8s, 16s, plafonne a 60s). Si le serveur est fondamentalement injoignable, il abandonne apres 5 tentatives.

q-089: Quelle difference entre un outil natif Hermes et un outil MCP ?

Quand utiliser un outil natif: quand la fonctionnalite est generique et utile a tous les utilisateurs (lecture de fichiers, execution de commandes, recherche web). Les outils natifs beneficient d'une integration profonde avec le systeme de toolsets, le modele de permissions, et le cache de prompt.

Quand utiliser MCP: quand vous voulez connecter un service externe (GitHub, Stripe, bases de donnees, API internes) sans ecrire de code dans Hermes. MCP est aussi le bon choix pour des outils specifiques a votre organisation ou pour prototyper rapidement une integration.

Coexistence: les deux types d'outils coexistent dans le meme registre. L'agent les utilise de maniere transparente, sans distinction dans son raisonnement. Les outils MCP apparaissent dans les memes toolsets de plateforme que les outils natifs.

q-090: Comment evaluer la confiance avant d'installer un MCP du catalogue ?

Hermes Agent propose un catalogue de serveurs MCP approuves par Nous Research, accessible via hermes mcp. Voici comment evaluer la confiance avant installation:

1. Le modele de confiance du catalogue

Chaque entree du catalogue correspond a un manifeste YAML (optional-mcps/<nom>/manifest.yaml) dans le depot GitHub de Hermes Agent. Ces manifestes sont ajoutes par PR (pull request) et revises par l'equipe Nous Research avant d'etre merges. Il n'y a pas de niveau de soumission communautaire: une entree dans le catalogue signifie qu'un humain de Nous l'a examinee.

2. Verifier le manifeste avant d'installer

Le manifeste est lisible sur GitHub:

https://github.com/NousResearch/hermes-agent/tree/main/optional-mcps

Examinez en priorite:

• source:: l'URL du depot upstream du serveur MCP. Verifiez qui le maintient, son historique de commits, et sa popularite.
• install.bootstrap:: les commandes executees lors de l'installation (pip install, npm install, etc.). Ces commandes s'executent avec vos permissions.
• transport.command:: la commande lancee pour demarrer le serveur. Verifiez qu'elle pointe vers le bon binaire.

3. Ce que le picker vous montre

La commande hermes mcp affiche pour chaque entree:

• Son statut (available, enabled, installed (disabled))
• Le type de transport (stdio ou HTTP)
• Le type d'authentification (API key, OAuth, aucune)
• L'URL source du manifeste (cliquable dans le dashboard web)

Le dashboard web (hermes dashboard) surface les memes informations avec l'URL source rendue en lien cliquable.

4. Selection des outils a l'installation

Apres configuration des credentials, Hermes sonde le serveur MCP et presente une checklist de tous les outils exposes. Vous choisissez exactement ceux que vous voulez exposer. C'est votre derniere ligne de defense: meme si vous faites confiance au serveur, vous pouvez n'exposer que les outils de lecture (ex: list_issues, search_code) et exclure les outils destructeurs (ex: delete_repo).

5. Points de vigilance

• Un manifeste approuve par Nous ne garantit pas l'absence de bugs ou de vulnerabilites dans le code du serveur MCP lui-meme. La revue porte sur le manifeste, pas sur l'audit complet du code source du serveur.
• Les serveurs stdio heritent d'un environnement filtre, mais les variables que vous ajoutez dans env (comme des tokens API) sont transmises au processus.
• Les serveurs avec auth: oauth demandent des permissions via le flux OAuth standard. Verifiez les scopes demandes avant d'approuver.
• Manifestes obsoletes: si un manifeste utilise un manifest_version plus recent que votre version de Hermes, le picker affiche un avertissement (⚠ '<nom>' requires a newer Hermes). Faites hermes update.

6. En resume, la checklist de confiance

1. L'entree est-elle dans le catalogue officiel? (hermes mcp catalog)
2. Le depot source est-il maintenu et repute? (verifiez source: dans le manifeste)
3. Les commandes bootstrap sont-elles comprehensibles et limitees?
4. Quels outils vais-je exposer? (utilisez la checklist interactive)
5. Ai-je besoin de donner un token API? Si oui, avec quelles permissions?

Pour les serveurs hors catalogue, vous les configurez manuellement dans config.yaml. La meme discipline s'applique: verifiez le depot source, comprenez ce que le serveur peut faire, et filtrez les outils exposes.

Sources

• Documentation officielle Hermes Agent (https://hermes-agent.nousresearch.com/docs/)
• Tools reference (https://hermes-agent.nousresearch.com/docs/reference/tools-reference)
• Toolsets reference (https://hermes-agent.nousresearch.com/docs/reference/toolsets-reference)
• MCP guide (https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp)
• CLI commands reference (https://hermes-agent.nousresearch.com/docs/reference/cli-commands)
• Depot NousResearch/hermes-agent, commit b4f8c491

Liens internes proposes

• Configurer Hermes Agent
• Depannage
• Modeles et providers
• Demarrer avec Hermes Agent
• Methodologie
• Sources