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
# 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
# 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
| Dimension | stdio-Server | HTTP-Server |
|---|---|---|
| Ausführungsort | Lokal (Kindprozess) | Remote (eigenständiger Dienst) |
| Kommunikationsmethode | stdin/stdout + JSON-RPC | HTTP-Anfrage |
| Lebenszyklus | Hermes verwaltet Start/Stopp | Unabhängig von Hermes |
| Latenz | Extrem niedrig (prozessinterne Kommunikation) | Hängt von der Netzwerklatenz ab |
| Authentifizierung | Übergeben von Umgebungsvariablen | Bearer-Token / OAuth 2.1 |
| Typische Szenarien | Lokales Git, Dateisysteme, Datenbanken | GitHub API, Linear, Sentry |
| Konfigurationskomplexität | Gering (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:
| State | Bedeutung |
|---|---|
| verfügbar | Installierbar, 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. |
| aktiviert | Remote-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:
- Konfigurationsanleitung: fordert Sie zur Eingabe des API-Schlüssels auf oder führt Sie durch den OAuth-Browser-Autorisierungsablauf.
- Tool-Erkennung: stellt eine Verbindung zum Server her und ruft die vollständige Liste der Tools ab, die er bereitstellt.
- 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
# 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
# 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
| Konfiguration | Verhalten | Anwendbare Szenarien |
|---|---|---|
| Nur include | Nur Tools in der include-Liste registrieren | Sicherheit zuerst, Prinzip der geringsten Rechte |
| Nur exclude | Alle Tools registrieren, exclude-Liste ausschließen | Bequemlichkeit zuerst, einige hochriskante Operationen ausschließen |
| Beide festlegen | include hat Vorrang, exclude wird ignoriert | — |
| Keines ist gesetzt | Alle vom Server bereitgestellten Tools registrieren | Diesem 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
# 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
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
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
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
| Problem | Mögliche Ursachen | Lösung |
|---|---|---|
| MCP-Tools werden nicht angezeigt | Server nicht aktiviert oder Verbindung fehlgeschlagen | Führe hermes mcp list aus, um den Status zu prüfen, und hermes mcp test, um die Verbindung zu testen |
| Tool-Filterung wird nicht wirksam | Der von Hermes registrierte Toolname wurde verwendet | Verwende den ursprünglichen MCP-Toolnamen (mit Bindestrichen, z. B. list-issues statt list_issues) |
| stdio-Server stürzt häufig ab | Fehlende Abhängigkeiten oder unzureichende Berechtigungen | Prüfen, ob der Befehl im PATH liegt; manuell einen Test ausführen |
| Zeitüberschreitung bei der OAuth-Autorisierung | Die 30 Sekunden für /reload-mcp reichen nicht aus | Zuerst hermes mcp login, dann nach Abschluss /reload-mcp |
| Umgebungsvariablen werden nicht wirksam | Nicht explizit im env:-Block deklariert | In mcp_servers.<name>.env deklarieren, sich nicht auf Shell-Umgebungsvariablen verlassen |
| Verbindung zum HTTP-Server verweigert | URL nicht erreichbar oder Authentifizierung fehlgeschlagen | URL und Authorization-Header prüfen, um die Netzwerkverbindung zu bestätigen. |