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

# Chemin du fichier : ~/.hermes/config.yaml
# 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

# Chemin du fichier : ~/.hermes/config.yaml
# 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

Dimensionserveur stdioserveur HTTP
Emplacement d'exécutionLocal (processus enfant)Distant (service autonome)
Méthode de communicationstdin/stdout + JSON-RPCRequête HTTP
Cycle de vieHermes gère le démarrage/l'arrêtIndépendant d'Hermes
LatenceExtrêmement faible (communication intra-processus)Dépend de la latence réseau
authentificationPassage de variables d'environnementJeton Bearer / OAuth 2.1
Scénarios typiquesGit local, systèmes de fichiers, bases de donnéesAPI GitHub, Linear, Sentry
Complexité de configurationFaible (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 :

StateSignification
disponibleInstallable, 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 :

  1. Guide de configuration: vous invite à saisir la clé API ou guide le flux d'autorisation OAuth dans le navigateur.
  2. Détection des outils: se connecte au serveur et récupère la liste complète des outils qu'il expose.
  3. 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

# Chemin du fichier : ~/.hermes/config.yaml
# 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

# Chemin du fichier : ~/.hermes/config.yaml
# 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

ConfigurationComportementScénarios applicables
Inclure uniquementEnregistrer uniquement les outils de la liste d'inclusionSécurité avant tout, principe du moindre privilège
Exclure uniquementEnregistrer tous les outils, exclure la liste d'exclusionPriorité à la commodité, exclure quelques opérations à haut risque
Définir les deuxL'inclusion est prioritaire, l'exclusion est ignorée—
Aucun des deux n'est définiEnregistrer tous les outils exposés par le serveurFaire 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

# Chemin du fichier : ~/.hermes/config.yaml
# 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

    env:
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

# Ajouter manuellement un serveur stdio
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

# ─── Navigation et installation ─────────────────────────────────────────────
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èmeCauses possiblesSolution
Les outils MCP n'apparaissent pasServeur non activé ou échec de connexionExécutez hermes mcp list pour vérifier l'état, hermes mcp test pour tester la connexion
Le filtrage des outils ne prend pas effetUtilisation du nom d'outil enregistré par HermesUtilisez le nom d'outil MCP d'origine (avec des tirets, par ex., list-issues au lieu de list_issues)
Le serveur stdio plante fréquemmentDépendances manquantes ou permissions insuffisantesVé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 pasD'abord hermes mcp login, puis /reload-mcp une fois terminé
Les variables d'environnement ne prennent pas effetNon 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éeURL inaccessible ou échec de l'authentificationVérifiez l'URL et l'en-tête Authorization pour confirmer la connectivité réseau.
autres extensions