Intégration MCP de Hermes Agent
MCP (Model Context Protocol) est un protocole ouvert proposé par Anthropic pour standardiser les interactions entre les LLM et les outils externes.
Hermes prend nativement en charge MCP, ce qui permet l'intégration avec tout service compatible MCP tel que GitHub, des bases de données, des systèmes de fichiers, des stacks de navigateur et des API internes sans modifier le code principal.
Ce chapitre approfondira les deux méthodes d'intégration de MCP, les stratégies de filtrage des outils, les mécanismes d'isolation de sécurité et le dépannage courant.
Qu'est-ce que MCP
MCP résout un problème pratique : à chaque nouvelle intégration de service, l'approche traditionnelle exige d'écrire du code d'adaptateur, de définir des schémas d'outils et de gérer l'authentification — chaque service est un travail ponctuel.
MCP standardise tout cela. Hermes peut s'intégrer directement à tout service qui implémente le protocole MCP, sans développement supplémentaire requis.
Rôle central de MCP :
Hermes Agent(MCP 客户端)
│
├── stdio ──→ MCP 服务器 A(本地子进程)
│ └── 暴露工具:git_commit, git_push...
│
├── HTTP ───→ MCP 服务器 B(远程服务)
│ └── 暴露工具:list_issues, create_issue...
│
└── HTTP ───→ MCP 服务器 C(远程 OAuth)
└── 暴露工具:search_docs, create_page...
L'installation standard inclut la prise en charge de MCP, aucune étape supplémentaire n'est requise. Tous les serveurs MCP dans~/.hermes/config.yamlla configuration centralisée dans.
MCP n'est pas un protocole propriétaire de Hermes — il est ouvert. Les serveurs écrits pour d'autres outils prenant en charge MCP (comme les serveurs MCP de Claude Code) peuvent être utilisés directement dans Hermes, et inversement.
Deux types de serveurs MCP
Serveur stdio local
S'exécute localement en tant que sous-processus, en communiquant avec Hermes via l'entrée/sortie standard (stdin/stdout).
La communication utilise le protocole JSON-RPC, chaque message étant séparé par un caractère de saut de ligne.
Scénarios applicables : les outils sont installés localement, nécessitant un accès à faible latence aux ressources locales (systèmes de fichiers, dépôts Git, bases de données locales).
Exemple
# Configuration du serveur MCP stdio
mcp_servers:
# Serveur GitHub : démarrer via npx
github:
command: "npx"
args: ["-y", "@modelcontextprotocol/server-github"]
env:
GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..."
# Serveur de système de fichiers : restreindre la portée d'accès de l'Agent
filesystem:
command: "npx"
args:
- "-y"
- "@modelcontextprotocol/server-filesystem"
- "/home/user/projects" # Autoriser l'accès uniquement à ce répertoire
# Serveur Git : démarrer via uvx
git:
command: "uvx"
args:
- "mcp-server-git"
- "--repository"
- "/home/user/project"
Le cycle de vie des serveurs stdio est géré par Hermes :
- Démarrage de session ou
/reload-mcpLorsque Hermes démarre un processus enfant - Lorsqu'une session se termine ou qu'un serveur est désactivé, Hermes met fin au processus enfant.
- Un processus enfant qui a planté redémarre automatiquement (avec un maximum de 3 tentatives).
Serveur HTTP distant
Se connecte directement aux points de terminaison MCP distants via des requêtes HTTP, prenant en charge plusieurs méthodes d'authentification.
Scénarios applicables : les outils sont hébergés à distance, ou votre organisation dispose déjà d'interfaces MCP.
Exemple
# Configuration du serveur HTTP MCP
mcp_servers:
# Méthode 1 : authentification par jeton Bearer statique
internal_api:
url: "https://mcp.internal.example.com/mcp"
headers:
Authorization: "Bearer ${MY_TOKEN}" # Prise en charge des variables d'environnement
# Méthode 2 : authentification OAuth 2.1(Linear、Sentry、Figma、Stripe etc.)
linear:
url: "https://mcp.linear.app/mcp"
auth: oauth
# Méthode 3 : fournisseurs nécessitant des clients OAuth pré-enregistrés
googledrive:
url: "https://drivemcp.googleapis.com/mcp/v1"
auth: oauth
oauth:
client_id: "<your-oauth-client-id>" # Récupération du pré-enregistrement
client_secret: "<your-oauth-client-secret>"
Comparaison de deux types
| Dimension | serveur stdio | serveur HTTP |
|---|---|---|
| Emplacement d'exécution | Local (processus enfant) | Distant (service autonome) |
| Méthode de communication | stdin/stdout + JSON-RPC | Requête HTTP |
| Cycle de vie | Hermes gère le démarrage/l'arrêt | Indépendant d'Hermes |
| Latence | Extrêmement faible (communication intra-processus) | Dépend de la latence réseau |
| authentification | Passage de variables d'environnement | Jeton Bearer / OAuth 2.1 |
| Scénarios typiques | Git local, systèmes de fichiers, bases de données | API GitHub, Linear, Sentry |
| Complexité de configuration | Faible (commande d'une ligne) | dans (nécessite une URL + configuration d'authentification) |
Répertoire MCP sélectionné par Nous
Hermes est livré avec un répertoire MCP validé par Nous Research, offrant une expérience d'installation en un clic.
Parcourir et installer
Ouvrez le sélecteur interactif (TUI) pour parcourir toutes les entrées du répertoire :
hermes mcp
Autres commandes :
# 纯文本列表(适合脚本化) hermes mcp catalog # 按名称一键安装 hermes mcp install n8n hermes mcp install github hermes mcp install linear
Le sélecteur interactif affiche l'état actuel de chaque entrée :
n8n available 管理和检查 n8n 工作流 linear enabled Linear 问题/项目管理(远程 OAuth) github installed (disabled) GitHub 仓库 + PR 工具 filesystem installed (enabled) 安全的文件系统操作 postgres available PostgreSQL 数据库查询 slack available Slack 消息和频道管理
Description du statut :
| State | Signification |
|---|---|
| disponible | Installable, pas encore installé |
| installé (activé) | Installé et activé, disponible pour être utilisé par l'Agent. |
| installé (désactivé) | Installé mais désactivé, non disponible pour l'Agent. |
| activé | Serveur OAuth distant, autorisé et activé. |
Version bureau : affichez la configuration dans le menu des paramètres :

Affichez la configuration dans le menu MCP à gauche du tableau de bord :

Ce qui se passe pendant l'installation
L'installation en un clic effectue automatiquement trois étapes :
- Guide de configuration: vous invite à saisir la clé API ou guide le flux d'autorisation OAuth dans le navigateur.
- Détection des outils: se connecte au serveur et récupère la liste complète des outils qu'il expose.
- Sélection des outils: affiche la liste des outils pour que vous puissiez cocher ceux que vous souhaitez activer (tous sélectionnés par défaut).
La troisième étape (sélection des outils) est un point de contrôle de sécurité important — vous n'avez pas besoin de tous les outils. Par exemple, si le serveur GitHub expose delete_repo et que vous n'en avez pas besoin, vous pouvez le décocher.
Filtrage des outils : n'exposez que ce dont vous avez besoin
Chaque serveur MCP prend en charge un filtrage granulaire des outils. C'est un mécanisme de sécurité clé pour réduire la surface d'attaque de l'agent.
mode include (liste blanche)
N'enregistrer que les outils de la liste ; exclure tous les autres :
Exemple
# mode include (liste blanche) — le choix le plus sûr.
mcp_servers:
github:
command: "npx"
args: ["-y", "@modelcontextprotocol/server-github"]
env:
GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..."
tools:
include:
- list_issues
- create_issue
- update_issue
- search_code
# Tous les outils autres que ces 4 ne seront pas enregistrés
mode d'exclusion (liste noire)
Exclure les outils de la liste ; enregistrer tous les autres :
Exemple
# Mode d'exclusion par liste noire — exclure les opérations à haut risque
mcp_servers:
stripe:
url: "https://mcp.stripe.com"
headers:
Authorization: "Bearer ${STRIPE_KEY}"
tools:
exclude:
- delete_customer
- refund_payment
- create_live_key
# Tout outil autre que ces 3 sera enregistré
Priorité des règles de filtrage
| Configuration | Comportement | Scénarios applicables |
|---|---|---|
| Inclure uniquement | Enregistrer uniquement les outils de la liste d'inclusion | Sécurité avant tout, principe du moindre privilège |
| Exclure uniquement | Enregistrer tous les outils, exclure la liste d'exclusion | Priorité à la commodité, exclure quelques opérations à haut risque |
| Définir les deux | L'inclusion est prioritaire, l'exclusion est ignorée | — |
| Aucun des deux n'est défini | Enregistrer tous les outils exposés par le serveur | Faire entièrement confiance à ce serveur MCP |
Désactiver les ressources et les prompts
En plus des outils, les serveurs MCP peuvent également exposer des ressources et des prompts. Si vous n'en avez pas besoin, vous pouvez les désactiver :
Exemple
# Référencer l'ensemble d'outils MCP dans la configuration de la plateforme
platform_toolsets:
cli:
- hermes-cli
- file
- terminal
- mcp-github # Outil MCP GitHub
mcp-linear # Outil MCP Linear
telegram:
- hermes-gateway
- mcp-github # Activer aussi les outils GitHub sur Telegram
discord:
- hermes-gateway
# Outils GitHub non activés sur Discord (politique de sécurité)
Isolation des variables d'environnement MCP
C'est la conception la plus facile à négliger, mais aussi la plus importante, des mécanismes de sécurité MCP de Hermes.
Le processus enfant stdio MCP reçoit unenvironnement filtréPar défaut, il ne transmet que les variables suivantes :
PATH, HOME, USER, LANG, LC_ALL, TERM, SHELL, TMPDIR 以及所有 XDG_* 变量
Toutes les autres variables d'environnement (clé API, jeton, mot de passe) sont bloquées.
Seules les variables d'environnement explicitement déclarées dans la configuration du serveur MCPenv:Seules les variables explicitement déclarées dans le bloc sont transmises au processus enfant :
Exemple
GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..." # Seule cette variable est transmise
# Même si vous avez exporté GITHUB_TOKEN dans le Shell,
# S'il n'est pas déclaré ici, il ne sera pas transmis au sous-processus MCP
Pourquoi est-ce conçu ainsi ? Supposons que vous ayez 10 clés API stockées dans .env (OpenAI, Anthropic, SerpAPI, Telegram Bot Token...). Si un serveur MCP pouvait lire toutes les variables d'environnement, un outil de serveur MCP malveillant pourrait voler tous les identifiants. L'isolation des variables d'environnement garantit qu'il ne peut voir que celle explicitement déclarée.
Les messages d'erreur sont automatiquement expurgés
Les messages d'erreur des outils MCP sont automatiquement assainis avant d'être renvoyés au LLM—les informations sensibles (clé API, jeton, mot de passe) sont remplacées par[REDACTED]。
Cela évite que l'Agent voie accidentellement des identifiants en clair lors de l'analyse d'erreurs.
Ajouter manuellement un serveur MCP
En plus de l'installation en un clic depuis le répertoire Nous, vous pouvez également ajouter manuellement n'importe quel serveur compatible MCP.
Exemple
hermes mcp add my-git-server \
--command "uvx" \
--args "mcp-server-git,--repository,/home/user/project"
# Ajouter manuellement un serveur HTTP
hermes mcp add internal-db \
--url "https://mcp.internal.example.com/db" \
--header "Authorization: Bearer ${DB_TOKEN}"
# Vérifier si la connexion est normale
hermes mcp test my-git-server
# Configurer le filtrage des outils
hermes mcp configure my-git-server
hermes mcp configureIl ouvre une interface interactive de sélection d'outils, vous permettant de cocher à nouveau les outils à activer.
Recharger la configuration MCP
Après avoir modifié la configuration MCP dans config.yaml, il n'est pas nécessaire de redémarrer tout l'Agent :
Exemple
hermes mcp # formulaDirectorySelectors interactif(TUI)
hermes mcp catalog # liste du catalogue en texte brut
hermes mcp install <name> # Installation en un clic depuis le répertoire
# ─── gestion manuelle ───────────────────────────────────────────────
hermes mcp add <name> --command <cmd> --args <...> # ajouter un serveur stdio
hermes mcp add <name> --url <url> # ajouter un serveur HTTP
hermes mcp remove <name> # Supprimer la configuration du serveur
hermes mcp list # Lister tous les serveurs configurés
hermes mcp test <name> # Tester la connexion au serveur
hermes mcp configure <name> # resélectionner les outils activés
# ─── authentification OAuth ─────────────────────────────────────────────
hermes mcp login <server> # Démarrer l'autorisation OAuth(attente maximale de 5 minutes)
# ─── Opérations d'exécution ─────────────────────────────────────────────
/reload-mcp # Recharger la configuration MCP dans la session
hermes mcp reload # Recharger depuis la ligne de commande
Dépannage courant
| Problème | Causes possibles | Solution |
|---|---|---|
| Les outils MCP n'apparaissent pas | Serveur non activé ou échec de connexion | Exécutez hermes mcp list pour vérifier l'état, hermes mcp test pour tester la connexion |
| Le filtrage des outils ne prend pas effet | Utilisation du nom d'outil enregistré par Hermes | Utilisez le nom d'outil MCP d'origine (avec des tirets, par ex., list-issues au lieu de list_issues) |
| Le serveur stdio plante fréquemment | Dépendances manquantes ou permissions insuffisantes | Vérifiez si la commande est dans le PATH, exécutez manuellement un test |
| Délai d'autorisation OAuth dépassé | Les 30 secondes pour /reload-mcp ne suffisent pas | D'abord hermes mcp login, puis /reload-mcp une fois terminé |
| Les variables d'environnement ne prennent pas effet | Non explicitement déclaré dans le bloc env: | Déclarez dans mcp_servers.<name>.env, ne vous fiez pas aux variables d'environnement du Shell |
| Connexion au serveur HTTP refusée | URL inaccessible ou échec de l'authentification | Vérifiez l'URL et l'en-tête Authorization pour confirmer la connectivité réseau. |