Serveurs MCP : étendre Hermes avec des outils externes
Hermes Agent est déjà un agent puissant avec ses 68 outils natifs. Mais imaginez pouvoir lui connecter instantanément GitHub, Notion, PostgreSQL, Stripe ou n'importe quelle API interne — sans écrire une seule ligne de code Python dans le cœur d'Hermes. C'est exactement ce que permet le MCP (Model Context Protocol), un standard ouvert créé par Anthropic qui établit un pont universel entre les agents IA et les serveurs d'outils externes.
Dans cet article avancé, nous explorons tout ce que MCP apporte à Hermes Agent : la configuration dans config.yaml, les deux transports supportés (stdio et HTTP), les exemples concrets avec les serveurs les plus populaires, la gestion sécurisée des tokens, la découverte automatique des outils, les permissions, et même comment créer votre propre serveur MCP.
Qu'est-ce que MCP et pourquoi c'est important ?
Le Model Context Protocol (MCP) est un protocole ouvert qui standardise la façon dont les modèles de langage interagissent avec des outils externes. Plutôt que d'intégrer chaque service individuellement, MCP définit une interface commune : un serveur MCP expose des outils via JSON-RPC, et n'importe quel client MCP (comme Hermes) peut les découvrir et les appeler automatiquement.
Pourquoi utiliser MCP avec Hermes ?
- Écosystème massif : des centaines de serveurs MCP existent déjà sur npm et PyPI — GitHub, filesystem, bases de données, API cloud, outils de productivité
- Configuration déclarative : ajoutez un serveur dans
config.yaml, redémarrez, et les outils apparaissent immédiatement - Isolation : chaque serveur MCP tourne dans son propre processus, avec ses propres variables d'environnement
- Dynamicité : les serveurs MCP peuvent signaler des changements dans leur liste d'outils en temps réel via la notification
notifications/tools/list_changed
Hermes intègre MCP nativement via le module tools/mcp_tool.py, qui gère le cycle de vie complet : connexion, découverte, appel d'outils, et nettoyage.
Configuration dans config.yaml
Toute la configuration MCP se trouve dans la section mcp_servers de ~/.hermes/config.yaml. Chaque entrée représente un serveur MCP nommé. Voici la structure complète :
mcp_servers:
nom_du_serveur:
# Pour les serveurs stdio (processus local) :
command: "npx"
args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"]
env:
VARIABLE: "valeur"
timeout: 120 # timeout par appel d'outil (secondes, défaut: 120)
connect_timeout: 60 # timeout de connexion initiale (défaut: 60)
serveur_http:
# Pour les serveurs distants (HTTP) :
url: "https://mcp.example.com/mcp"
headers:
Authorization: "Bearer sk-..."
timeout: 180
Les variables d'environnement utilisent la syntaxe ${VAR} et sont résolues automatiquement depuis ~/.hermes/.env et os.environ. Cela signifie que vos tokens API ne doivent jamais être écrits en clair dans config.yaml :
mcp_servers:
github:
command: npx
args: ["-y", "@modelcontextprotocol/server-github"]
env:
GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"
La résolution suit cet ordre de priorité : ~/.hermes/.env → variables système → valeurs par défaut.
Les deux transports : stdio et HTTP
Hermes supporte deux modes de transport MCP, chacun adapté à un cas d'usage différent.
Transport stdio
Le transport stdio lance le serveur MCP comme un sous-processus. Hermes communique avec lui via l'entrée et la sortie standard (stdin/stdout). C'est le mode le plus courant et le plus simple :
mcp_servers:
time:
command: uvx
args: ["mcp-server-time"]
filesystem:
command: npx
args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
Avantages du stdio :
- Aucun serveur réseau à gérer
- Sécurité maximale (pas d'exposition réseau)
- Isolation naturelle (processus séparé)
- Idéal pour les outils locaux comme le filesystem ou Git
Transport HTTP (StreamableHTTP)
Le transport HTTP connecte Hermes à un serveur MCP distant via une URL. C'est idéal pour les API cloud et les services managés :
mcp_servers:
notion:
url: https://mcp.notion.com/mcp
custom_api:
url: https://my-mcp-server.example.com/mcp
headers:
Authorization: "Bearer ${MY_API_KEY}"
X-Custom-Header: "value"
timeout: 180
Avantages du HTTP :
- Accès aux services cloud (Notion, Stripe, etc.)
- Partage d'un serveur entre plusieurs agents
- Scalabilité naturelle
- Supporte les headers d'authentification
Exemples concrets : les serveurs MCP populaires
GitHub — Opérations sur les repositories
Le serveur MCP officiel GitHub donne à Hermes la capacité de créer des issues, gérer des pull requests, lire le code source et bien plus :
mcp_servers:
github:
command: npx
args: ["-y", "@modelcontextprotocol/server-github"]
env:
GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"
Une fois configuré, les outils GitHub apparaissent dans le registre d'Hermes sous le toolset mcp-github. Vous pouvez alors demander à Hermes : "Crée une issue sur mon repo pour le bug X" ou "Liste les PRs ouvertes sur le projet Y".
Filesystem — Accès sécurisé au système de fichiers
Le serveur filesystem permet à Hermes de lire et écrire dans des répertoires que vous autorisez explicitement :
mcp_servers:
filesystem:
command: npx
args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/documents"]
Point de sécurité important : le chemin passé en argument délimite strictement le périmètre d'accès. Hermes ne pourra ni lire ni écrire en dehors de ce répertoire. C'est une sandbox intégrée.
Recherche web — Accéder au web en temps réel
Plusieurs serveurs MCP de recherche web existent. Voici un exemple avec un serveur de recherche :
mcp_servers:
web_search:
command: uvx
args: ["mcp-server-web-search"]
env:
SEARCH_API_KEY: "${SEARCH_API_KEY}"
Notion — Base de connaissances
Notion propose un serveur MCP natif accessible via HTTP :
mcp_servers:
notion:
url: https://mcp.notion.com/mcp
Serveur de temps — Exemple minimal
Le serveur de temps est l'exemple le plus simple pour vérifier que votre configuration MCP fonctionne :
mcp_servers:
time:
command: uvx
args: ["mcp-server-time"]
Découverte automatique des outils
C'est l'un des aspects les plus puissants de l'intégration MCP dans Hermes. Lors du démarrage, Hermes effectue automatiquement pour chaque serveur configuré :
- Connexion au serveur (via stdio ou HTTP)
- Appel
tools/listpour découvrir tous les outils disponibles - Enregistrement dans le registre d'outils sous le toolset
mcp-<nom_du_serveur> - Exposition au modèle avec les descriptions et schémas JSON Schema des paramètres
Hermes assigne à chaque outil MCP un nom préfixé comme mcp__github__create_issue ou mcp__filesystem__read_file. Le modèle voit ces outils exactement comme les outils natifs — il n'y a aucune différence du point de vue de l'agent.
Rafraîchissement dynamique
Les serveurs MCP peuvent envoyer la notification notifications/tools/list_changed pour signaler que leur liste d'outils a changé. Hermes réagit en effectuant un cycle complet de "désenregistrement puis re-découverte" : il supprime tous les outils du toolset concerné, puis les redécouvre.
Pour forcer manuellement le rechargement de tous les serveurs MCP sans redémarrer Hermes, utilisez la commande /reload-mcp dans le CLI.
Sécurité et permissions
La sécurité est un aspect central de l'intégration MCP dans Hermes. Plusieurs couches de protection sont en place.
Isolation des variables d'environnement
Les variables d'environnement définies dans la section env d'un serveur MCP ne sont transmises qu'à ce sous-processus. Elles ne polluent pas l'environnement global d'Hermes ni les autres serveurs. Si un serveur MCP est compromis, il n'a accès qu'à ses propres tokens.
Désactivation sélective
Vous pouvez désactiver des serveurs MCP entiers ou filtrer des outils spécifiques :
mcp_servers:
github:
command: npx
args: ["-y", "@modelcontextprotocol/server-github"]
env:
GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"
disabled: true # Serveur désactivé mais conservé dans la config
Permissions par outil
Hermes supporte le filtrage par outil pour restreindre quels outils MCP sont disponibles. Vous pouvez lister les outils autorisés ou bloqués par serveur, offrant un contrôle granulaire sur ce que l'agent peut faire avec chaque service externe.
Bonnes pratiques de sécurité
- Ne jamais mettre de tokens en clair dans
config.yaml— utilisez toujours${VAR}et le fichier.env - Limiter les chemins du filesystem MCP au strict nécessaire
- Désactiver les serveurs MCP que vous n'utilisez pas
- Auditer régulièrement les serveurs MCP actifs avec
/toolsdans le CLI - Privilégier le transport stdio quand possible (pas d'exposition réseau)
Créer un serveur MCP simple
Créer votre propre serveur MCP est étonnamment simple grâce au SDK mcp de Python. Voici un serveur minimal qui expose un outil de calcul :
#!/usr/bin/env python3
"""Mon premier serveur MCP - outils mathématiques."""
from mcp.server.fastmcp import FastMCP
mcp = FastMCP(
"mon_serveur",
instructions="Outils mathématiques avancés.",
)
@mcp.tool()
def calculer(expression: str) -> str:
'Évalue une expression mathématique en toute sécurité.'
allowed = set("0123456789+-*/().% ")
if not all(c in allowed for c in expression):
return f"Erreur: caractères non autorisés dans {expression}"
try:
result = eval(expression) # noqa: S307
return str(result)
except Exception as e:
return f"Erreur d'évaluation: {e}"
@mcp.tool()
def conversion_unites(valeur: float, de: str, vers: str) -> str:
'Convertit une valeur entre unités (km/mi, kg/lb, C/F).'
conversions = {
("km", "mi"): valeur * 0.621371,
("mi", "km"): valeur * 1.60934,
("kg", "lb"): valeur * 2.20462,
("lb", "kg"): valeur * 0.453592,
("C", "F"): valeur * 9/5 + 32,
("F", "C"): (valeur - 32) * 5/9,
}
cle = (de.lower(), vers.lower())
if cle not in conversions:
return f"Conversion {de} -> {vers} non supportée"
return f"{valeur} {de} = {conversions[cle]:.4f} {vers}"
if __name__ == "__main__":
mcp.run()
Pour brancher ce serveur à Hermes, ajoutez-le dans config.yaml :
mcp_servers:
maths:
command: python3
args: ["/chemin/vers/mon_serveur_mcp.py"]
Après redémarrage, Hermes aura accès aux outils calculer et conversion_unites automatiquement.
Hermes comme serveur MCP
Hermes Agent peut aussi fonctionner comme serveur MCP ! La commande hermes mcp serve expose les conversations Hermes comme outils MCP, permettant à d'autres clients MCP (Claude Code, Cursor, Codex) de lister les conversations, lire les messages, envoyer des messages et gérer les permissions.
{
"mcpServers": {
"hermes": {
"command": "hermes",
"args": ["mcp", "serve"]
}
}
}
Cette fonctionnalité est implémentée dans mcp_serve.py et expose 10 outils incluant conversations_list, messages_read, messages_send, events_poll et channels_list.
Dépannage
Le serveur MCP ne se connecte pas
Symptôme : les outils MCP n'apparaissent pas dans la liste des outils.
Solutions :
1. Vérifiez que le paquet mcp est installé : pip install mcp
2. Vérifiez le chemin de la commande (utilisez le chemin absolu si nécessaire)
3. Testez le serveur manuellement : exécutez la commande avec les mêmes arguments dans un terminal
4. Augmentez connect_timeout si le serveur est lent à démarrer (certains serveurs Node.js via npx téléchargent des dépendances au premier lancement)
Erreur "command not found"
Si npx ou uvx ne sont pas trouvés, c'est un problème de PATH. Solution :
- Utilisez le chemin absolu : /usr/bin/npx ou /home/user/.local/bin/uvx
- Ou assurez-vous que votre PATH est correctement configuré dans ~/.hermes/.env
Variables d'environnement non résolues
Si ${GITHUB_TOKEN} apparaît littéralement dans les logs au lieu de la valeur résolue :
- Vérifiez que la variable est bien définie dans ~/.hermes/.env
- Vérifiez que le nom correspond exactement (majuscules/minuscules)
- N'oubliez pas les guillemets autour de la valeur : "${GITHUB_TOKEN}"
Timeout sur les appels d'outils
Si les appels d'outils MCP échouent régulièrement par timeout :
- Augmentez timeout dans la configuration du serveur (défaut : 120 secondes)
- Augmentez connect_timeout pour les connexions initiales lentes (défaut : 60 secondes)
Commandes de diagnostic
# Lister tous les outils MCP actifs
hermes chat --list-tools | grep mcp__
# Recharger tous les serveurs MCP (dans le CLI)
/reload-mcp
# Vérifier la configuration
hermes config | grep -A 20 mcp_servers
Conclusion
Les serveurs MCP transforment Hermes Agent d'un outil puissant en une plateforme modulaire et extensible. Avec une simple déclaration dans config.yaml, vous ajoutez instantanément des capacités qui seraient autrement impossibles ou demanderaient des développements significatifs.
Ce que nous avons couvert :
- Configuration simple dans la section mcp_servers de config.yaml
- Deux transports : stdio pour les outils locaux, HTTP pour les services cloud
- Exemples concrets : GitHub, filesystem, recherche web, Notion
- Variables d'environnement sécurisées avec la syntaxe ${VAR} et isolation par serveur
- Découverte automatique : les outils MCP apparaissent comme des outils natifs dans le registre
- Rafraîchissement dynamique via notifications/tools/list_changed et /reload-mcp
- Sécurité multicouche : isolation des processus, sandbox filesystem, permissions granulaires
- Création de serveurs personnalisés avec le SDK Python mcp
- Hermes comme serveur MCP pour l'intégration avec d'autres clients MCP
Chaque nouveau serveur MCP que vous configurez étend les capacités d'Hermes sans aucune modification de code. C'est la promesse d'un agent IA véritablement composable.
Articles liés :
- /article/hermes-agent-outils-disponibles — Les 68 outils natifs d'Hermes Agent
- /article/hermes-agent-configurer-modeles-providers — Configuration des modèles et providers
- /article/hermes-agent-connecter-telegram — Connecter Telegram à Hermes
- /article/hermes-agent-delegation-sous-agents — Délégation de tâches avec des sous-agents
- /article/hermes-agent-cron-jobs-automatisation — Automatiser avec les cron jobs