Hermify
Torna al blog
AI AgentsMCPTroubleshooting

Gli strumenti MCP di Hermes Agent non caricano: fix veloce

Il server MCP è configurato ma nessuno strumento appare in sessione. Cinque guasti silenziosi e il percorso di diagnosi per sbloccare ciascuno.

Di Hermify Team||6 min di lettura
Scena tecnica scura con una connessione MCP interrotta e il testo MCP Not Loading

Hai aggiunto un server MCP a ~/.hermes/config.yaml, riavviato il gateway e chiesto a Hermes di elencare i suoi strumenti. Niente di nuovo. Nessun errore, nessun warning, gateway.log in silenzio. Questo post è il percorso più corto tra quel silenzio e un mcp_<server>_<strumento> funzionante nella tua sessione.

Cinque modalità di guasto spiegano quasi tutti i casi segnalati e ognuna si nasconde in un punto diverso. Buona notizia: hermes mcp list, hermes mcp test e un unico flag di log ti diranno in meno di due minuti quale delle cinque ti riguarda.

Perché esistono i guasti silenziosi

La configurazione MCP è la superficie con meno log utile di tutto Hermes. Quando il loader non riesce ad avviare un server, a importare l'extra Python mcp o a fare il parse del blocco mcp_servers, il fallimento viene loggato a livello DEBUG e non arriva mai in gateway.log nell'installazione standard. Dal tuo lato sembra che la config sia stata accettata e che gli strumenti semplicemente non esistano.

Il fix inizia dalla visibilità, prima di toccare qualsiasi altra cosa. Riavvia Hermes con log verboso così il loader ti dice perché si è arreso:

hermes serve --verbose
# oppure, se avvii con docker compose:
HERMES_LOG_LEVEL=DEBUG docker compose up

Ora rilancia hermes mcp list. Se il tuo server appare in lista ma senza strumenti attaccati, la connessione tiene ma la discovery è fallita. Se il server non compare, il loader non lo ha mai registrato. Questa biforcazione ti dice quale dei fix qui sotto si applica.

Causa 1: l'extra Python mcp non è installato

Se hai costruito Hermes dai sorgenti o fissato un tag preciso, il pacchetto mcp è un extra opzionale e non entra con l'install di default. Senza di lui, ogni voce sotto mcp_servers viene ignorata in silenzio. È la causa numero uno nei setup su misura.

Reinstalla con l'extra abilitato:

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

Se il gateway ora parte e tenta di raggiungere il server, ti mancava l'SDK. Se il log continua a dire mcp module not available, l'extra non è finito nell'interprete che Hermes usa davvero: controlla hermes --version per il path del venv e rilancia l'install lì dentro.

Causa 2: la tua indentazione YAML è sfasata di uno spazio

YAML scarta in silenzio qualsiasi blocco la cui indentazione non combaci con quella del genitore. Una tab sfuggita, un - alla profondità sbagliata o due punti senza virgolette dentro una stringa di comando fanno sparire tutta la mappa mcp_servers senza una riga di warning.

Il formato sicuro è indentazione a due spazi, virgolette intorno a qualsiasi cosa contenga due punti e liste con -:

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

Due controlli rapidi: lancia python -c "import yaml; yaml.safe_load(open('$HOME/.hermes/config.yaml'))" per confermare che il file venga parsato, poi hermes mcp list per confermare che i nomi appaiano. Se il file parsa ma il blocco è vuoto dal punto di vista di Hermes, l'indentazione è sbagliata anche se il YAML è legale.

Causa 3: manca node o npx sull'host

La maggior parte dei server MCP della community arriva come pacchetti npm e viene lanciata con npx -y @modelcontextprotocol/server-<nome>. Se l'host non ha Node.js nel PATH, il sottoprocesso muore prima di stampare qualsiasi cosa e Hermes annota il fallimento solo a DEBUG. È la causa più comune nei container Docker minimali.

Testa l'avvio fuori da Hermes per prima cosa:

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

Se uno dei tre comandi fallisce, installa Node.js nello stesso ambiente in cui gira Hermes. In Docker significa aggiungere nodejs e npm alla tua immagine o partire da una base che li abbia già. Non c'è modo per Hermes di lanciare un binario Node che non esiste.

Causa 4: il server si connette ma i suoi strumenti non arrivano in sessione

Vedi il server in hermes mcp list, hermes mcp test <server> scopre i suoi strumenti e comunque dentro la sessione non c'è niente di nuovo di richiamabile. È il guasto documentato in issue #51587 e issue #71736: la discovery ha funzionato ma gli strumenti non sono mai stati iniettati nel toolset della sessione.

I workaround affidabili:

  • Lancia /reload-mcp dentro la tua sessione Hermes, o riavvia il gateway per intero. Certe build popolano il toolset una sola volta al boot e mancano i server che salgono in ritardo.
  • Controlla il campo enabled_toolsets della sessione. Se è troppo ristretto (per esempio la sessione ACP fissa ["hermes-acp"]), gli strumenti MCP restano fuori per design e il toolset va allargato.
  • Verifica che il tuo provider supporti davvero l'uso di strumenti. I modelli Ollama devono partire con un template di tool compatibile con Hermes, e i modelli locali vecchi segnalano gli strumenti scoperti ma non li chiamano mai.

Causa 5: il tuo provider scarta le tool call in silenzio

Anche con il server in piedi e gli strumenti registrati, certi provider rimuovono il payload di tool prima che il modello lo veda. Il sintomo è lo stesso di un MCP rotto: lo strumento esiste ma non succede niente quando lo chiedi.

Controllo da due minuti: sposta la sessione su un provider noto per il tool calling (un modello recente di Anthropic, OpenAI o Groq) e fai la stessa domanda. Se lì lo strumento parte, il problema è il tuo provider o la tua scelta di modello, non MCP. Se ancora non parte, torna alla Causa 4.

Il percorso di diagnosi, in ordine

Esegui questi comandi in questo ordine e fermati appena qualcosa cambia ciò che vedi:

  1. hermes serve --verbose - ora i fallimenti stampano su stdout.
  2. python -c "import yaml; yaml.safe_load(open('$HOME/.hermes/config.yaml'))" - conferma che il file almeno parsa.
  3. hermes mcp list - mostra ciò che il loader ha accettato.
  4. hermes mcp test <server> - mostra se connessione e discovery tengono.
  5. hermes mcp health - snapshot di stato per server quando devi passare la palla a qualcuno.
  6. /reload-mcp dentro la tua sessione, o riavvio completo del gateway.
  7. Cambia provider per due minuti, per un A/B.

Per un giro completo sulla superficie di diagnosi, la guida a debugging e osservabilità di Hermes copre gateway.log, il tracing per strumento e come tailare tutto pulito. Se stai ancora montando il tuo primo server MCP, la guida al setup di MCP percorre la forma del file di config prima che uno qualsiasi dei guasti sopra diventi possibile.

Salta tutta questa superficie

Ogni guasto di questo post nasce da un disallineamento tra Hermes e il suo host: un extra Python assente, un binario Node assente, un permesso sbagliato sul file di config, un bug nell'ordine di boot della sessione. Hermify gestisce tutta quella superficie per te.

Inizia con Hermify per far girare un Hermes Agent gestito su Telegram con MCP già cablato, l'extra mcp installato, npx disponibile sull'host e il reload al cambio di config che funziona di serie. Tieni la tua config MCP, tieni la tua memoria, e smetti di diagnosticare l'indentazione YAML un martedì sera.

Fonti

Avvia il tuo Hermes Agent

Porta la tua chiave API, collega Telegram e ottieni un agente IA che migliora da solo, online in 60 secondi.

Inizia ora