Hermes Agent e MCP: como configurar servidores que aparecem de verdade

Um servidor MCP conectar não é a mesma coisa que um agente usar ele. Aprendi isso do jeito caro: 157 ferramentas conectadas, zero chamadas, e um modelo jurando que as ferramentas não existiam. As ferramentas existiam. A configuração estava certa. O que faltava era timing, e nenhum quickstart avisa sobre timing.

Isto é a configuração, a UI atual, e as correções de produção para rodar servidores MCP contra o Hermes Agent, checado na v0.21.5, commit 9c6fe3aa.

Servidores MCP no Hermes Agent começam num bloco só

Todo servidor MCP com quem o Hermes fala vive sob mcp_servers no ~/.hermes/config.yaml, uma entrada por servidor, e o formato da entrada depende de o servidor falar stdio ou HTTP.

mcp_servers:
  project_fs:
    command: "npx"
    args:
      ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/project"]
    tools:
      include: [read_file, list_directory]

  github:
    url: "https://api.githubcopilot.com/mcp/"
    headers:
      Authorization: "Bearer ${env:GITHUB_TOKEN}"
    tools:
      exclude: [delete_repo]

Um servidor stdio recebe command, args e env. Um servidor HTTP recebe url e headers em vez disso, mais chaves de TLS (ssl_verify, client_cert, client_key) quando o endpoint precisa de mTLS. Os dois formatos compartilham enabled, timeout, connect_timeout, trust e uma política tools com globs de include/exclude mais toggles de resources/prompts para os wrappers utilitários que o Hermes adiciona por cima. ${VAR} e o ${env:VAR} no estilo Cursor resolvem a partir do .env do perfil ativo, então um trecho copiado de uma config do Cursor ou do Claude Code funciona sem mudar nada.

Duas chaves importam mais do que o quickstart deixa claro. lazy: true registra as ferramentas de um servidor a partir do cache de schema em disco na inicialização e só faz spawn ou conecta na primeira chamada real, o que é o padrão certo para um servidor que você usa raramente. idle_timeout_seconds e max_lifetime_seconds reciclam um servidor stdio depois que ele fica ocioso ou velho, o que importa para qualquer servidor que vaza memória lentamente.

Você não precisa editar YAML na mão para o caso comum. hermes mcp add escreve a entrada para você, e hermes mcp test <server> conecta e lista o que descobre:

Adicione e confira um servidor

1. Servidor stdio local

   $ hermes mcp add github --command npx --args -y @modelcontextprotocol/server-github

2. Confirmar que conecta

   $ hermes mcp test github

Dentro de uma sessão rodando, /reload-mcp capta uma mudança de config sem precisar reiniciar. Esse slash command é a correção para um bug que me custou um restart em junho: um servidor MCP adicionado depois de o gateway já ter subido conectava, mas o toolset dele nunca registrava para ativação até o gateway reiniciar. /reload-mcp é o remédio documentado hoje. Se você está rodando uma versão do Hermes anterior a esse slash command, reserve um restart toda vez que você tocar em mcp_servers.

A central de comando de MCP substituiu a antiga aba de MCP

O Hermes Desktop tinha uma aba de MCP. Na v0.21.5 ele tem uma página de Connectors em vez disso, e a mudança é mais que estética. O release trouxe um catálogo de servidores curados e aprovados pela Nous, health checks por conexão, e prompts de “Connect now” que disparam no momento em que você instala um plugin que vem com os próprios servidores MCP, então as ferramentas e skills de um plugin recém-instalado entram no ar em todo chat que você já tem aberto, não só nos novos. A mesma janela de release adicionou mcp.discovery_concurrency para limitar quantos servidores o Hermes sonda de uma vez durante a descoberta no startup, o tipo de controle que você só precisa quando tem servidores o suficiente para a própria descoberta virar um bottleneck.

O tool search faz deferral de toda ferramenta MCP, o orçamento é a única variável

No momento em que qualquer ferramenta de MCP ou plugin existe numa sessão, o Hermes move ela para trás de uma ferramenta de busca em vez de listar no system prompt. Isso não é condicionado a quantas ferramentas você tem. O tool_search.py ativa sempre que existe qualquer ferramenta com deferral possível, ponto final. Não existe um limiar de “abaixo de 10 por cento do contexto, lista tudo” no código.

O que a configuração de fato controla é o tamanho da listagem compacta que o Hermes ainda embute para as ferramentas com deferral: threshold_pct, 5,0 por padrão, limitado por listing_max_tokens, 4.000 tokens por padrão. O orçamento é min(listing_max_tokens, threshold_pct% da context window), e um tamanho de contexto desconhecido cai para um teto fixo de 10.000 tokens, que é 5 por cento de uma janela típica de 200K. Suba o threshold_pct e você ganha uma listagem embutida mais rica, ao custo de espaço de prompt em todo turno. Abaixe e o modelo depende mais da própria ferramenta de busca.

Esse é o mecanismo que faz do hard-scope das ferramentas de um agente um ganho muito menor do que parece. Minha frota tinha 114 ferramentas de MCP escondidas atrás da busca em junho. O custo em tokens de “ferramentas demais” já estava mitigado pelo deferral; a única coisa que o hard-scope me comprou foi risco. Mais sobre isso abaixo.

hermes mcp serve: o Hermes como fonte para outros agentes

A configuração acima é o Hermes como client de MCP, puxando ferramentas para dentro. O Hermes também consegue rodar como servidor. hermes mcp serve inicia um servidor MCP de stdio que expõe as suas conversas de mensagem como ferramentas: listar conversas, ler histórico, mandar mensagens, fazer poll de eventos ao vivo, gerenciar aprovações. Aponte o Claude Code, o Cursor ou o Codex para ele:

{
  "mcpServers": {
    "hermes": { "command": "hermes", "args": ["mcp", "serve"] }
  }
}

A docstring do próprio módulo diz que ele equivale à superfície da bridge de canais de 9 ferramentas do OpenClaw, o que te diz de onde veio a pressão de design: no momento em que um runtime self-hosted expõe os canais dele para um agente de código via MCP, o outro precisa fazer o mesmo.

Hermes Agent e MCP em produção: as correções que importam

Tudo acima é a documentação. Tudo abaixo é o que a documentação não avisa, aprendido rodando uma frota de agentes do Paperclip no Hermes desde junho.

O que MCP em produção realmente me ensinou

1. Junho157 ferramentas, zero chamadas

   Todo agente tinha o toolset completo conectado por um gateway agregador na frente de 7 servidores MCP de backend. Eles não chamaram nada e reportaram que as ferramentas não existiam. A causa real estava no agent.log: o gateway fazia cold-spawn dos 7 backends por sessão, 4,5 a 27 segundos, além da janela de descoberta de menos de um segundo do próprio Hermes. Um backend aquecido responde tools/list em cerca de 10 milissegundos. Os agentes simplesmente nunca esperaram tanto tempo.

2. JunhoControl plane e data plane são trabalhos diferentes

   A correção não foi abandonar o gateway agregador, ele se paga como catálogo administrativo. A correção foi parar de rotear o tráfego quente por ele. O mcp-pooler mantém uma sessão persistente e aquecida com o gateway, faz cache do tools/list, e faz proxy do tools/call, então toda sessão de agente de vida curta vê descoberta em cerca de 50 milissegundos em vez de dezenas de segundos. No config.yaml isso significa uma entrada HTTP só, apontada para o pooler, não uma entrada por backend.

3. Junhohermes mcp test prova menos do que parece

   O comando conecta e lista ferramentas, o que é uma checagem estática: prova spawn mais tools/list, nada sobre auth ou disponibilidade sob carga. Prova real precisou de um tools/call mais uma sondagem direta na API. A documentação de hoje descreve os mesmos três exit codes, 0 conectado, 1 falhou, 3 não configurado, que ainda significam a mesma coisa limitada.

4. JunhoA flag de hard-scope substitui, ela não estreita

   Dar escopo a um agente com a flag de toolset do Hermes substituía o toolset base inteiro em vez de adicionar a ele, o que removeu o terminal e as skills do agente e deixou ele um zumbi sem mãos. Combinado com o tool search já pagando o custo em tokens de um toolset grande, o hard-scope deixou de valer o risco. Migrei para soft scope: doutrina num TOOLS.md mais uma cerca de projeto, e isso se sustentou. Um agente com o pool completo simplesmente nunca tocava no namespace que ele foi instruído a deixar quieto.

5. JunhoValide o consumidor antes de construir a fonte

   Passei uma tarde construindo quatro namespaces de MCP com hard-scope antes de checar como a flag de toolset de fato consumia eles. O trabalho inteiro da tarde foi deletado uma hora depois de passar nos próprios testes, porque eu tinha provado a coisa errada corretamente.

6. Em andamentoO agente é um narrador não confiável

   Toda falha de MCP que eu debuguei acreditando no relato do próprio agente me custou tempo. O agent.log estava certo todas as vezes em que a história do agente estava errada. Quando uma chamada de ferramenta falha, leia o log antes de ler a transcrição do chat.

A corrida de cold-spawn e o erro de escopo estão escritos por completo no Lab: 157 ferramentas e zero chamadas e valide o consumo antes de construir a fonte. Os MCPs de dado atrás dessa frota eram Ubersuggest, GA4 e Search Console, catalogados no gateway agregador e alcançados pelo pooler. Nada disso era exótico. Toda falha remetia a uma corrida, à semântica real de uma flag, ou a um erro de sequenciamento, nunca ao modelo.

Palavras que te dão prova, não narração

1. 01

   Faça o agente chamar a ferramenta, não só nomear ela.

   O tool search e o hermes mcp test, os dois, parecem na listagem. Uma ferramenta que aparece num resultado de busca não foi comprovada a retornar nada.

   Digite isto

   Chama essa ferramenta uma vez com um argumento real agora e cola o resultado bruto. Não me diz que ela está disponível, me mostra ela retornando dado.

2. 02

   Quando ele diz que uma ferramenta não existe, pede a linha do log, não a desculpa.

   O agente narra uma falha. O agent.log registra ela. Os dois discordam mais do que você imaginaria.

   Em vez de

   Por que essa ferramenta não funcionou?

   Digite isto

   Abre o agent.log e cita a linha exata da última chamada de MCP que falhou. Não resume, cita.

3. 03

   Antes de confiar num hard scope, pergunte o que ele de fato removeu.

   A flag de toolset do Hermes substitui o toolset base em vez de estreitar ele. Um agente que perdeu o terminal muitas vezes não vai avisar isso por conta própria.

   Digite isto

   Lista toda ferramenta que você tem acesso agora, depois me diz o que você tinha antes de eu adicionar a flag -t.

Antes de conectar um servidor MCP novo no Hermes

• ✓Obrigatório:
  Decida stdio ou HTTP primeiro, as chaves não se misturam.command/args/env para um processo local, url/headers para um endpoint remoto. Um formato por servidor.
• ✓Obrigatório:
  Recorra a tools.include antes de recorrer a uma flag de escopo.O tool search já paga a maior parte do custo em tokens de um toolset grande. Um agente amplo cercado por doutrina é mais seguro que um com hard-scope que perdeu o próprio terminal.
• ✓Obrigatório:
  Trate o hermes mcp test como smoke test, não como health check.Ele prova que o servidor sobe e lista ferramentas. Prove um tools/call real separadamente antes de confiar na conexão.
• ✓Obrigatório:
  Se um servidor está atrás de um gateway agregador, ponha um pooler aquecido na frente dele.Sessões de agente efêmeras não sobrevivem a um cold spawn de 4 a 27 segundos. Um tools/list com cache e uma sessão upstream aquecida sobrevivem.
• ✓Obrigatório:
  Quando um agente diz que uma ferramenta não existe, abra o agent.log antes de acreditar.O agente narra. O log é a verdade no terreno.

Hermes Agent e MCP, respostas rápidas

Como eu adiciono um servidor MCP no Hermes Agent?+

Adicione uma entrada sob mcp_servers no ~/.hermes/config.yaml, ou rode hermes mcp add <nome> --command ... --args ... para um servidor stdio (use --url para HTTP em vez de um command). Confirme com hermes mcp test <nome>, depois recarregue uma sessão rodando com /reload-mcp em vez de reiniciar.

O que é MCP?+

MCP (Model Context Protocol) é o protocolo padrão que deixa um agente de IA conectar a ferramentas e fontes de dado externas por uma interface comum, em vez de uma integração sob medida para cada uma. Um servidor MCP expõe dados e ações, como ler um arquivo, consultar um banco ou chamar uma API, como ferramentas que o agente pode chamar.

O que é a central de comando de MCP no Hermes Agent?+

A partir da v0.21.5, a antiga aba de MCP do Hermes Desktop é a página de Connectors: um catálogo de servidores curados, health checks por conexão, e um fluxo de 'Connect now' que ativa as ferramentas MCP de um plugin recém-instalado em todo chat já aberto.

O tool search do Hermes Agent só ativa acima de um limiar de tokens?+

Não. O tool search ativa no momento em que qualquer ferramenta de MCP ou plugin existe na sessão, não importa quantas sejam. A única coisa configurável é o tamanho da listagem embutida para as ferramentas com deferral, 5 por cento da context window por padrão, limitado a 4.000 tokens.

O Claude Code consegue usar o Hermes Agent como servidor MCP?+

Sim. hermes mcp serve expõe suas conversas de mensagem, listar, ler histórico, mandar, fazer poll de eventos, gerenciar aprovações, como ferramentas MCP que qualquer client pode chamar, Claude Code, Cursor ou Codex inclusos.

Por que o meu agente no Hermes diz que as ferramentas MCP dele não existem?+

Geralmente uma corrida de descoberta, não uma ferramenta de fato ausente. Se o servidor está atrás de um gateway agregador que faz cold-spawn dos backends por sessão, a descoberta pode levar segundos enquanto a própria janela do Hermes é de menos de um segundo. Leia o agent.log antes de confiar na explicação do agente, e ponha um pooler aquecido na frente do gateway se cold starts forem a causa.