Hermify
Zurück zum Blog
AI AgentsMCPTroubleshooting

MCP-Tools in Hermes Agent laden nicht: schnelle Lösung

Ihr MCP-Server ist konfiguriert, aber keine Tools in der Sitzung. Fünf stille Fehlermodi und der Diagnosepfad, um jeden zu beheben.

Von Hermify Team||6 Min. Lesezeit
Dunkle technische Szene mit einer defekten MCP-Verbindung und dem Text MCP Not Loading

Sie haben einen MCP-Server in ~/.hermes/config.yaml hinzugefügt, das Gateway neu gestartet und Hermes gebeten, seine Tools aufzulisten. Nichts Neues da. Keine Fehlermeldung, keine Warnung, gateway.log schweigt. Dieser Beitrag ist der kürzeste Weg von dieser Stille zu einem funktionierenden mcp_<server>_<tool> in Ihrer Sitzung.

Fünf Fehlermodi decken fast alle gemeldeten Fälle ab, und jeder versteckt sich an einer anderen Stelle. Die gute Nachricht: hermes mcp list, hermes mcp test und ein einziges Log-Level-Flag zeigen Ihnen in unter zwei Minuten, welcher der fünf Sie betrifft.

Warum stille Fehler überhaupt auftreten

MCP-Fehlkonfiguration ist die am schlechtesten geloggte Oberfläche in Hermes. Wenn der Loader einen Server nicht starten, den Python-Extra mcp nicht importieren oder den mcp_servers-Block nicht parsen kann, wird der Fehler auf DEBUG protokolliert und erreicht in der Standardinstallation nie gateway.log. Aus Ihrer Sicht sieht es so aus, als sei die Konfiguration akzeptiert worden und die Tools existierten schlicht nicht.

Die Lösung beginnt mit Sichtbarkeit, bevor Sie irgendetwas anderes anfassen. Starten Sie Hermes mit ausführlichem Logging neu, damit der Loader Ihnen sagt, warum er aufgegeben hat:

hermes serve --verbose
# oder, falls Sie über docker compose starten:
HERMES_LOG_LEVEL=DEBUG docker compose up

Führen Sie nun erneut hermes mcp list aus. Wenn Ihr Server in der Liste erscheint, aber keine Tools daran hängen, steht die Verbindung, aber die Tool-Discovery ist fehlgeschlagen. Fehlt der Server komplett, hat der Loader ihn nie registriert. Diese Verzweigung sagt Ihnen, welcher der folgenden Fixes greift.

Ursache 1: der Python-Extra mcp ist nicht installiert

Wenn Sie Hermes aus dem Quellcode gebaut oder auf einen bestimmten Tag gepinnt haben, ist das mcp-Paket ein optionaler Extra und wird vom Standard-Install nicht mitgezogen. Ohne ihn wird jeder Eintrag unter mcp_servers stillschweigend ignoriert. Das ist die häufigste Ursache bei individuellen Setups.

Neu installieren mit aktiviertem Extra:

cd ~/.hermes/hermes-agent
uv pip install -e ".[mcp]"
hermes serve --verbose

Startet Ihr Gateway jetzt und versucht, den Server zu erreichen, hat Ihnen das SDK gefehlt. Sagt das Log immer noch mcp module not available, ist der Extra nicht im Interpreter gelandet, in dem Hermes tatsächlich läuft: prüfen Sie hermes --version für den venv-Pfad und führen Sie den Install darin erneut aus.

Ursache 2: Ihre YAML-Einrückung ist um einen Zeichen daneben

YAML verwirft still jeden Block, dessen Einrückung nicht zur Elternebene passt. Ein verirrter Tab, ein - auf falscher Tiefe oder ein unkotierter Doppelpunkt in einer Command-Zeichenkette lassen die gesamte mcp_servers-Map ohne eine Warnzeile verschwinden.

Die sichere Form: zwei Leerzeichen Einrückung, Anführungszeichen um alles mit einem Doppelpunkt und Listen mit -:

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    enabled: true
  stripe:
    url: "https://mcp.stripe.com/v1/sse"
    enabled: true

Zwei schnelle Prüfungen: python -c "import yaml; yaml.safe_load(open('$HOME/.hermes/config.yaml'))" bestätigt, dass die Datei überhaupt parst, danach zeigt hermes mcp list, ob die Namen auftauchen. Parst die Datei, ist aber der Block aus Sicht von Hermes leer, ist die Einrückung falsch, obwohl das YAML syntaktisch gültig ist.

Ursache 3: node oder npx fehlt auf dem Host

Die meisten Community-MCP-Server werden als npm-Pakete ausgeliefert und mit npx -y @modelcontextprotocol/server-<name> gestartet. Fehlt Node.js im PATH des Hosts, stirbt der Subprozess, bevor er irgendetwas ausgibt, und Hermes vermerkt den Fehler nur auf DEBUG. Das ist die häufigste Ursache in minimalen Docker-Containern.

Testen Sie den Start zuerst außerhalb von Hermes:

node --version
npx --version
npx -y @modelcontextprotocol/server-filesystem /tmp

Schlägt einer der drei Befehle fehl, installieren Sie Node.js in der Umgebung, in der Hermes läuft. Unter Docker heißt das, nodejs und npm zu Ihrem Image hinzuzufügen oder ein Base-Image zu wählen, das sie mitbringt. Hermes kann keine Node-Binary starten, die nicht existiert.

Ursache 4: der Server verbindet sich, aber seine Tools tauchen nie in der Sitzung auf

Sie sehen den Server in hermes mcp list, hermes mcp test <server> entdeckt seine Tools, und trotzdem ist innerhalb der Sitzung nichts Neues aufrufbar. Das ist der in Issue #51587 und Issue #71736 dokumentierte Fehler: die Discovery hat funktioniert, aber die Tools wurden nie in das Session-Toolset injiziert.

Zuverlässige Workarounds:

  • Führen Sie /reload-mcp in Ihrer Hermes-Sitzung aus oder starten Sie das Gateway vollständig neu. Manche Builds befüllen das Toolset nur einmal beim Start und übersehen Server, die später hochkommen.
  • Prüfen Sie das Feld enabled_toolsets der Sitzung. Ist es zu eng gefasst (die ACP-Sitzung fixiert es beispielsweise auf ["hermes-acp"]), sind MCP-Tools per Design ausgeschlossen und das Toolset muss geweitet werden.
  • Vergewissern Sie sich, dass Ihr Anbieter Tool-Nutzung wirklich unterstützt. Ollama-Modelle müssen mit einem Hermes-kompatiblen Tool-Template starten, und ältere lokale Modelle melden entdeckte Tools, rufen sie aber nie auf.

Ursache 5: Ihr Anbieter verwirft Tool-Calls still

Selbst mit einem laufenden Server und registrierten Tools entfernen manche Anbieter das Tool-Payload, bevor das Modell es sieht. Das Symptom ist identisch mit einem kaputten MCP: das Tool existiert, aber nichts passiert, wenn Sie es aufrufen.

Zwei-Minuten-Test: schalten Sie die Sitzung auf einen bewährten Tool-Calling-Anbieter (ein aktuelles Modell von Anthropic, OpenAI oder Groq) und stellen Sie dieselbe Frage. Feuert das Tool dort, liegt es an Ihrem Anbieter oder Ihrer Modellwahl, nicht an MCP. Feuert es weiterhin nicht, zurück zu Ursache 4.

Der Diagnosepfad, der Reihe nach

Führen Sie dies in dieser Reihenfolge aus und halten Sie an, sobald sich etwas an dem ändert, was Sie sehen:

  1. hermes serve --verbose - Fehler landen nun auf stdout.
  2. python -c "import yaml; yaml.safe_load(open('$HOME/.hermes/config.yaml'))" - bestätigt, dass die Datei überhaupt parst.
  3. hermes mcp list - zeigt, was der Loader akzeptiert hat.
  4. hermes mcp test <server> - zeigt, ob Verbindung und Discovery stehen.
  5. hermes mcp health - ein Statussnapshot pro Server, wenn Sie etwas übergeben müssen.
  6. /reload-mcp in Ihrer Sitzung oder ein vollständiger Neustart des Gateways.
  7. Wechseln Sie für zwei Minuten den Anbieter, für einen A/B.

Für einen kompletten Rundgang durch die Diagnoseoberfläche behandelt der Debugging- und Observability-Leitfaden von Hermes gateway.log, das Tracing pro Tool und wie Sie alles sauber im Tail verfolgen. Wenn Sie noch Ihren ersten MCP-Server aufsetzen, führt Sie der MCP-Setup-Leitfaden durch die Form der Konfigurationsdatei, bevor eine der obigen Pannen überhaupt möglich wird.

Umgehen Sie die gesamte Oberfläche

Jede Panne in diesem Beitrag entsteht aus einer Diskrepanz zwischen Hermes und seinem Host: ein fehlender Python-Extra, ein fehlender Node-Binary, eine falsche Berechtigung auf der Konfigurationsdatei, ein Bug in der Boot-Reihenfolge der Sitzung. Hermify betreibt diese gesamte Oberfläche für Sie.

Starten Sie mit Hermify, um einen verwalteten Hermes Agent auf Telegram zu betreiben, mit bereits verdrahtetem MCP, installiertem mcp-Extra, npx auf dem Host und Reload bei Konfigurationsänderung ab Werk. Sie behalten Ihre MCP-Konfiguration, behalten Ihr Gedächtnis und diagnostizieren an einem Dienstagabend keine YAML-Einrückung mehr.

Quellen

Betreiben Sie Ihren eigenen Hermes Agent

Bringen Sie Ihren API-Schlüssel mit, verbinden Sie Telegram und erhalten Sie in 60 Sekunden einen selbstlernenden KI-Agenten.

Loslegen