Hermes Agent MCP-Integration

MCP (Model Context Protocol) ist ein offenes Protokoll, das von Anthropic vorgeschlagen wurde, um die Interaktionen zwischen LLMs und externen Tools zu standardisieren.

Hermes unterstützt MCP nativ und ermöglicht die Integration mit jedem MCP-kompatiblen Dienst wie GitHub, Datenbanken, Dateisystemen, Browser-Stacks und internen APIs, ohne den Kerncode zu ändern.

Dieses Kapitel befasst sich eingehend mit den beiden MCP-Integrationsmethoden, Tool-Filterungsstrategien, Sicherheitsisolationsmechanismen und gängiger Fehlerbehebung.


Was ist MCP

MCP löst ein praktisches Problem: Bei jeder neuen Dienstintegration erfordert der traditionelle Ansatz das Schreiben von Adaptercode, das Definieren von Tool-Schemas und die Handhabung der Authentifizierung – jeder Dienst ist eine Einzelanfertigung.

MCP standardisiert all dies. Hermes kann sich direkt mit jedem Dienst integrieren, der das MCP-Protokoll implementiert, ohne dass zusätzliche Entwicklung erforderlich ist.

Die Kernrolle von 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...

Die Standardinstallation enthält MCP-Unterstützung, es sind keine zusätzlichen Schritte erforderlich. Alle MCP-Server in~/.hermes/config.yamlzentraler Konfiguration in.

MCP ist kein proprietäres Protokoll von Hermes – es ist offen. Server, die für andere MCP-unterstützende Tools geschrieben wurden (wie die MCP-Server von Claude Code), können direkt in Hermes verwendet werden, und umgekehrt.


Zwei Arten von MCP-Servern

Lokaler stdio-Server

Läuft lokal als Unterprozess und kommuniziert mit Hermes über Standardeingabe/-ausgabe (stdin/stdout).

Die Kommunikation verwendet das JSON-RPC-Protokoll, wobei jede Nachricht durch ein Zeilenumbruchzeichen getrennt wird.

Anwendbare Szenarien: Tools sind lokal installiert und erfordern einen latenzarmen Zugriff auf lokale Ressourcen (Dateisysteme, Git-Repositories, lokale Datenbanken).

Beispiel

# Dateipfad: ~/.hermes/config.yaml
# MCP-stdio-Server-Konfiguration
mcp_servers
:
 # GitHub-Server: Start über npx
  github
:
    command
: "npx"
    args
: ["-y", "@modelcontextprotocol/server-github"]
    env
:
      GITHUB_PERSONAL_ACCESS_TOKEN
: "ghp_..."

  # Dateisystem-Server: Zugriffsbereich des Agenten einschränken
  filesystem
:
    command
: "npx"
    args
:
     - "-y"
      - "@modelcontextprotocol/server-filesystem"
      - "/home/user/projects"     # Nur Zugriff auf dieses Verzeichnis erlauben

  # Git-Server: Start über uvx
  git
:
    command
: "uvx"
    args
:
     - "mcp-server-git"
      - "--repository"
      - "/home/user/project"

Der Lebenszyklus von stdio-Servern wird von Hermes verwaltet:

  • Sitzungsstart oder/reload-mcpWenn Hermes einen Kindprozess startet
  • Wenn eine Sitzung endet oder ein Server deaktiviert wird, beendet Hermes den Kindprozess.
  • Ein abgestürzter Kindprozess wird automatisch neu gestartet (mit bis zu 3 Wiederholungsversuchen).

Remote-HTTP-Server

Verbindet sich direkt über HTTP-Anfragen mit entfernten MCP-Endpunkten und unterstützt mehrere Authentifizierungsmethoden.

Anwendbare Szenarien: Tools werden remote gehostet, oder Ihre Organisation verfügt bereits über MCP-Schnittstellen.

Beispiel

# Dateipfad: ~/.hermes/config.yaml
# MCP-HTTP-Server-Konfiguration
mcp_servers
:
 # Methode 1: Statische Bearer-Token-Authentifizierung
  internal_api
:
    url
: "https://mcp.internal.example.com/mcp"
    headers
:
      Authorization
: "Bearer ${MY_TOKEN}"    # Unterstützung von Umgebungsvariablen

  # Methode 2:OAuth 2.1-Authentifizierung(Linear、Sentry、Figma、Stripe usw.)
  linear
:
    url
: "https://mcp.linear.app/mcp"
    auth
: oauth

  # Methode 3: Anbieter, die vorregistrierte OAuth-Clients benötigen
  googledrive
:
    url
: "https://drivemcp.googleapis.com/mcp/v1"
    auth
: oauth
    oauth
:
      client_id
: "<your-oauth-client-id>"       # Abruf der Vorregistrierung
      client_secret
: "<your-oauth-client-secret>"

Vergleich zweier Typen

Dimensionstdio-ServerHTTP-Server
AusführungsortLokal (Kindprozess)Remote (eigenständiger Dienst)
Kommunikationsmethodestdin/stdout + JSON-RPCHTTP-Anfrage
LebenszyklusHermes verwaltet Start/StoppUnabhängig von Hermes
LatenzExtrem niedrig (prozessinterne Kommunikation)Hängt von der Netzwerklatenz ab
AuthentifizierungÜbergeben von UmgebungsvariablenBearer-Token / OAuth 2.1
Typische SzenarienLokales Git, Dateisysteme, DatenbankenGitHub API, Linear, Sentry
KonfigurationskomplexitätGering (Einzeilenbefehl)in (erfordert URL + Authentifizierungskonfiguration)

Von Nous kuratiertes MCP-Verzeichnis

Hermes wird mit einem von Nous Research geprüften MCP-Verzeichnis geliefert und bietet eine Installation mit einem Klick.

Durchsuchen und installieren

Öffnen Sie die interaktive Auswahl (TUI), um alle Verzeichniseinträge zu durchsuchen:

hermes mcp

Weitere Befehle:

# 纯文本列表(适合脚本化)
hermes mcp catalog

# 按名称一键安装
hermes mcp install n8n
hermes mcp install github
hermes mcp install linear

Die interaktive Auswahl zeigt den aktuellen Status jedes Eintrags:

n8n          available              管理和检查 n8n 工作流
linear       enabled                Linear 问题/项目管理(远程 OAuth)
github       installed (disabled)   GitHub 仓库 + PR 工具
filesystem   installed (enabled)    安全的文件系统操作
postgres     available               PostgreSQL 数据库查询
slack        available               Slack 消息和频道管理

Statusbeschreibung:

StateBedeutung
verfügbarInstallierbar, noch nicht installiert
installiert (aktiviert)Installiert und aktiviert, für die Nutzung durch den Agenten verfügbar.
installiert (deaktiviert)Installiert, aber deaktiviert, nicht für den Agenten verfügbar.
aktiviertRemote-OAuth-Server, autorisiert und aktiviert.

Desktop-Version: Konfiguration im Einstellungsmenü anzeigen:

Konfiguration im MCP-Menü auf der linken Seite des Dashboards anzeigen:

Was während der Installation passiert

Die Ein-Klick-Installation erledigt automatisch drei Schritte:

  1. Konfigurationsanleitung: fordert Sie zur Eingabe des API-Schlüssels auf oder führt Sie durch den OAuth-Browser-Autorisierungsablauf.
  2. Tool-Erkennung: stellt eine Verbindung zum Server her und ruft die vollständige Liste der Tools ab, die er bereitstellt.
  3. Tool-Auswahl: zeigt die Tool-Liste an, damit Sie die Tools auswählen können, die Sie aktivieren möchten (standardmäßig sind alle ausgewählt).

Der dritte Schritt (Tool-Auswahl) ist ein wichtiger Sicherheitskontrollpunkt — Sie benötigen nicht jedes Tool. Wenn beispielsweise der GitHub-Server delete_repo bereitstellt und Sie es nicht benötigen, können Sie es abwählen.


Tool-Filterung: nur das bereitstellen, was Sie benötigen

Jeder MCP-Server unterstützt eine feingranulare Tool-Filterung. Dies ist ein zentraler Sicherheitsmechanismus, um die Angriffsfläche des Agenten zu reduzieren.

Include-Modus (Whitelist)

Nur Tools in der Liste registrieren; alle anderen ausschließen:

Beispiel

# Dateipfad: ~/.hermes/config.yaml
# Include-Whitelist-Modus — die sicherste Wahl.
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
      # Alle Tools außer diesen 4 werden nicht registriert

Ausschlussmodus (Blacklist)

Tools in der Liste ausschließen; alle anderen registrieren:

Beispiel

# Dateipfad: ~/.hermes/config.yaml
# Blacklist-Ausschlussmodus — risikoreiche Operationen ausschließen
mcp_servers
:
  stripe
:
    url
: "https://mcp.stripe.com"
    headers
:
      Authorization
: "Bearer ${STRIPE_KEY}"
    tools
:
      exclude
:
       - delete_customer
        - refund_payment
        - create_live_key
      # Jedes Tool außer diesen 3 wird registriert

Priorität der Filterregel

KonfigurationVerhaltenAnwendbare Szenarien
Nur includeNur Tools in der include-Liste registrierenSicherheit zuerst, Prinzip der geringsten Rechte
Nur excludeAlle Tools registrieren, exclude-Liste ausschließenBequemlichkeit zuerst, einige hochriskante Operationen ausschließen
Beide festlegeninclude hat Vorrang, exclude wird ignoriert—
Keines ist gesetztAlle vom Server bereitgestellten Tools registrierenDiesem MCP-Server vollständig vertrauen

Ressourcen und Prompts deaktivieren

Zusätzlich zu Tools können MCP-Server auch Ressourcen und Prompts bereitstellen. Wenn du sie nicht benötigst, kannst du sie deaktivieren:

Beispiel

# Dateipfad: ~/.hermes/config.yaml
# MCP-Toolset in Plattformkonfiguration referenzieren
platform_toolsets:
  cli:
    - hermes-cli
    - file
    - terminal
- mcp-github # GitHub-MCP-Tool
mcp-linear # Linear-MCP-Tool

  telegram:
    - hermes-gateway
- mcp-github # GitHub-Tools auch auf Telegram aktivieren

  discord:
    - hermes-gateway
# GitHub-Tools auf Discord nicht aktiviert (Sicherheitsrichtlinie)

Isolierung der MCP-Umgebungsvariablen

Dies ist das am leichtesten zu übersehende und zugleich wichtigste Design in den MCP-Sicherheitsmechanismen von Hermes.

Der MCP-stdio-Kindprozess erhält einegefilterte UmgebungStandardmäßig werden nur die folgenden Variablen übergeben:

PATH, HOME, USER, LANG, LC_ALL, TERM, SHELL, TMPDIR
以及所有 XDG_* 变量

Alle anderen Umgebungsvariablen (API Key, Token, Passwort) werden blockiert.

Nur Umgebungsvariablen, die explizit in der MCP-Server-Konfiguration deklariert sindenv:Nur Variablen, die explizit im Block deklariert sind, werden an den Kindprozess übergeben:

Beispiel

    env:
GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..." # Nur diese Variable wird übergeben
# Selbst wenn Sie GITHUB_TOKEN in der Shell exportiert haben,
# Wenn es hier nicht deklariert wird, wird es nicht an den MCP-Subprozess übergeben

Warum ist es so gestaltet? Angenommen, Sie haben 10 API-Schlüssel in .env gespeichert (OpenAI, Anthropic, SerpAPI, Telegram Bot Token...). Wenn ein MCP-Server alle Umgebungsvariablen lesen könnte, könnte ein bösartiges MCP-Server-Tool alle Zugangsdaten stehlen. Die Isolierung von Umgebungsvariablen stellt sicher, dass er nur die explizit deklarierte sehen kann.

Fehlermeldungen werden automatisch unkenntlich gemacht

Fehlermeldungen von MCP-Tools werden automatisch bereinigt, bevor sie an das LLM zurückgegeben werden – sensible Informationen (API-Schlüssel, Token, Passwort) werden ersetzt durch[REDACTED]。

Dies verhindert, dass der Agent beim Analysieren von Fehlern versehentlich Klartext-Anmeldedaten sieht.


MCP-Server manuell hinzufügen

Neben der Installation mit einem Klick aus dem Nous-Verzeichnis können Sie auch jeden MCP-kompatiblen Server manuell hinzufügen.

Beispiel

# stdio-Server manuell hinzufügen
hermes mcp add my-git-server \
  --command "uvx" \
  --args "mcp-server-git,--repository,/home/user/project"

# HTTP-Server manuell hinzufügen
hermes mcp add internal-db \
  --url "https://mcp.internal.example.com/db" \
  --header "Authorization: Bearer ${DB_TOKEN}"

# Testen, ob die Verbindung normal ist
hermes mcp test my-git-server

# Tool-Filterung konfigurieren
hermes mcp configure my-git-server

hermes mcp configureEs öffnet eine interaktive Tool-Auswahloberfläche, auf der Sie die zu aktivierenden Tools erneut überprüfen können.


MCP-Konfiguration neu laden

Nach dem Ändern der MCP-Konfiguration in config.yaml muss der gesamte Agent nicht neu gestartet werden:

Beispiel

# ─── Durchsuchen und Installation ─────────────────────────────────────────────
hermes mcp # Interaktive formulaDirectorySelectors(TUI)
hermes mcp catalog # Klartext-Katalogauflistung
hermes mcp install <name> # Ein-Klick-Installation aus dem Verzeichnis

# ─── Manuelle Verwaltung ───────────────────────────────────────────────
hermes mcp add <name> --command <cmd> --args <...> # stdio-Server hinzufügen
hermes mcp add <name> --url <url> # HTTP-Server hinzufügen
hermes mcp remove <name> # Serverkonfiguration entfernen
hermes mcp list # Alle konfigurierten Server auflisten
hermes mcp test <name> # Serververbindung testen
hermes mcp configure <name> # aktivierte Tools erneut auswählen

# ─── OAuth-Authentifizierung ─────────────────────────────────────────────
hermes mcp login <server> # OAuth-Autorisierung starten(max. 5 Minuten warten)

# ─── Laufzeitoperationen ─────────────────────────────────────────────
/reload-mcp # SessioninsideAgainaddload MCP-Konfiguration
hermes mcp reload # Von der Kommandozeile neu laden

Häufige Fehlerbehebung

ProblemMögliche UrsachenLösung
MCP-Tools werden nicht angezeigtServer nicht aktiviert oder Verbindung fehlgeschlagenFühre hermes mcp list aus, um den Status zu prüfen, und hermes mcp test, um die Verbindung zu testen
Tool-Filterung wird nicht wirksamDer von Hermes registrierte Toolname wurde verwendetVerwende den ursprünglichen MCP-Toolnamen (mit Bindestrichen, z. B. list-issues statt list_issues)
stdio-Server stürzt häufig abFehlende Abhängigkeiten oder unzureichende BerechtigungenPrüfen, ob der Befehl im PATH liegt; manuell einen Test ausführen
Zeitüberschreitung bei der OAuth-AutorisierungDie 30 Sekunden für /reload-mcp reichen nicht ausZuerst hermes mcp login, dann nach Abschluss /reload-mcp
Umgebungsvariablen werden nicht wirksamNicht explizit im env:-Block deklariertIn mcp_servers.<name>.env deklarieren, sich nicht auf Shell-Umgebungsvariablen verlassen
Verbindung zum HTTP-Server verweigertURL nicht erreichbar oder Authentifizierung fehlgeschlagenURL und Authorization-Header prüfen, um die Netzwerkverbindung zu bestätigen.
Weitere Erweiterungen