Hermes Agent não carrega ferramentas MCP: como resolver

Você adicionou um servidor MCP em ~/.hermes/config.yaml, reiniciou o gateway e pediu ao Hermes para listar as ferramentas. Nada de novo. Sem erro, sem aviso, gateway.log em silêncio. Este post é o caminho mais curto entre esse silêncio e um mcp_<servidor>_<ferramenta> funcionando na sua sessão.

Cinco modos de falha explicam quase todos os casos reportados, e cada um se esconde em um lugar diferente. A boa notícia: hermes mcp list, hermes mcp test e uma única flag de log dizem em menos de dois minutos qual dos cinco te pegou.

Por que existem essas falhas silenciosas

A configuração MCP é a superfície do Hermes com menos log útil. Quando o loader não consegue subir um servidor, importar o extra Python mcp ou parsear o bloco mcp_servers, a falha é registrada em nível DEBUG e nunca sobe para o gateway.log na instalação padrão. Do seu lado parece que a config foi aceita e as ferramentas simplesmente não existem.

A saída é subir a visibilidade antes de mexer em qualquer outra coisa. Reinicie o Hermes com log verboso para o loader te contar por que desistiu:

hermes serve --verbose
# ou, se você sobe pelo docker compose:
HERMES_LOG_LEVEL=DEBUG docker compose up

Agora rode hermes mcp list de novo. Se o servidor aparece na lista mas sem ferramentas penduradas, a conexão subiu porém o discovery falhou. Se o servidor não aparece, o loader nem chegou a registrá-lo. Essa bifurcação te diz qual dos fixes abaixo você precisa.

Causa 1: o extra Python mcp não está instalado

Se você compilou o Hermes a partir do código ou fixou uma tag específica, o pacote mcp é um extra opcional e não vem no install padrão. Sem ele, cada entrada dentro de mcp_servers é ignorada em silêncio. É a causa número um em setups customizados.

Reinstale com o extra habilitado:

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

Se o gateway sobe agora e tenta alcançar o servidor, o que faltava era o SDK. Se o log ainda diz mcp module not available, o extra não foi para o interpretador que o Hermes está de fato executando: cheque o hermes --version para descobrir o caminho do venv e rode o install lá dentro.

Causa 2: a indentação do YAML está um espaço fora

O YAML descarta em silêncio qualquer bloco cuja indentação não bate com a do pai. Um tab perdido, um - na profundidade errada ou dois-pontos sem aspas dentro de uma string de comando fazem sumir o mapa mcp_servers inteiro sem uma linha de aviso.

O formato seguro é indentação de dois espaços, aspas em qualquer coisa com dois-pontos e listas com -:

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

Duas checagens rápidas: rode python -c "import yaml; yaml.safe_load(open('$HOME/.hermes/config.yaml'))" para confirmar que o arquivo é parseável, depois hermes mcp list para confirmar que os nomes aparecem. Se o arquivo parseia mas o bloco está vazio do ponto de vista do Hermes, a indentação está errada mesmo com sintaxe legal.

Causa 3: falta node ou npx no host

A maioria dos servidores MCP da comunidade vem como pacotes npm e é lançada com npx -y @modelcontextprotocol/server-<nome>. Se o host não tem Node.js no PATH, o subprocesso morre antes de imprimir qualquer coisa e o Hermes registra a falha só em DEBUG. É a causa mais comum dentro de containers Docker minimalistas.

Teste o lançamento fora do Hermes primeiro:

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

Se qualquer um dos três falha, instale o Node.js no mesmo ambiente em que o Hermes roda. No Docker isso significa adicionar nodejs e npm na sua imagem ou escolher uma base que já tenha. Não tem como o Hermes lançar um binário Node que não existe.

Causa 4: o servidor conecta mas as ferramentas não vão para a sessão

Você vê o servidor no hermes mcp list, o hermes mcp test <servidor> descobre as ferramentas e mesmo assim nada novo é callable dentro da sessão. É a falha documentada na issue #51587 e na issue #71736: o discovery funcionou, mas as ferramentas nunca foram injetadas no toolset da sessão.

Os workarounds confiáveis são:

• Rode /reload-mcp dentro da sua sessão do Hermes, ou reinicie o gateway inteiro. Alguns builds populam o toolset uma única vez no boot e pulam servidores que sobem tarde.
• Cheque o campo enabled_toolsets da sessão. Se estiver muito escopado (por exemplo, a sessão ACP hardcoda ["hermes-acp"]), as ferramentas MCP ficam de fora por design e o toolset precisa ser aberto.
• Confirme que o seu provider realmente suporta uso de ferramentas. Modelos Ollama precisam subir com um template de tool compatível com o Hermes, e modelos locais mais antigos reportam as ferramentas descobertas mas nunca chamam.

Causa 5: seu provider derruba as tool calls em silêncio

Mesmo com o servidor no ar e as ferramentas registradas, alguns providers removem o payload de tool antes de o modelo ver. O sintoma é idêntico a um MCP quebrado: a ferramenta existe mas não acontece nada quando você pede.

Checagem de dois minutos: troque a sessão para um provider comprovado em tool calling (qualquer modelo recente da Anthropic, OpenAI ou Groq) e faça a mesma pergunta. Se lá a ferramenta dispara, o problema é seu provider ou sua escolha de modelo, não o MCP. Se ainda não dispara, volta para a Causa 4.

O caminho de diagnóstico, em ordem

Rode isto nesta ordem e pare assim que algo mudar o que você vê:

1. hermes serve --verbose - agora as falhas vão para stdout.
2. python -c "import yaml; yaml.safe_load(open('$HOME/.hermes/config.yaml'))" - confirma que o arquivo pelo menos parseia.
3. hermes mcp list - mostra o que o loader aceitou.
4. hermes mcp test <servidor> - mostra se conexão e discovery estão de pé.
5. hermes mcp health - snapshot de status por servidor quando precisa entregar algo para alguém.
6. /reload-mcp dentro da sua sessão, ou um restart completo do gateway.
7. Troque de provider por dois minutos para um A/B.

Para um tour completo da superfície de diagnóstico, o guia de debugging e observabilidade do Hermes cobre gateway.log, o tracing por ferramenta e como dar tail em tudo sem enlouquecer. Se você ainda está montando seu primeiro servidor MCP, o guia de setup de MCP explica o formato do arquivo de config antes de qualquer uma das falhas acima aparecer.

Pule essa superfície inteira

Cada falha deste post vem de um descompasso entre o Hermes e o host: um extra Python que não está, um binário Node que não está, uma permissão errada no arquivo de config, um bug de ordem de boot da sessão. A Hermify roda essa superfície inteira por você.

Comece com a Hermify para rodar um Hermes Agent gerenciado no Telegram com MCP já cabeado, o extra mcp instalado, npx disponível no host e o reload ao mudar a config funcionando de fábrica. Você mantém sua config de MCP, mantém sua memória e para de diagnosticar indentação de YAML numa terça à noite.

Fontes

• Configuração MCP inválida é invisível - issue #31246
• Ferramentas MCP conectam mas não vão para a sessão - issue #51587
• Disponibilidade inconsistente de ferramentas MCP com Ollama - issue #71736
• Documentação MCP do Hermes Agent
• Guia de debugging do Model Context Protocol