MCP (Model Context Protocol)

O MCP deixa o Hermes Agent se conectar a servidores de ferramentas externos, para que o agente use ferramentas que vivem fora do próprio Hermes — GitHub, bancos de dados, sistemas de arquivos, pilhas de navegador, APIs internas e mais.

Se você já quis que o Hermes usasse uma ferramenta que já existe em outro lugar, o MCP costuma ser o jeito mais limpo de fazer isso.

Vindo do Claude Code?

O bloco mcpServers do seu ~/.claude.json corresponde a mcp_servers no config.yaml do Hermes — e o hermes import-agent claude-code migra tudo (junto com skills e instruções) automaticamente. Veja Importar de outros agentes.

O que o MCP te dá

• Acesso a ecossistemas de ferramentas externos sem precisar escrever antes uma ferramenta nativa do Hermes
• Servidores stdio locais e servidores MCP HTTP remotos na mesma configuração
• Descoberta e registro automáticos de ferramentas na inicialização
• Invólucros utilitários para recursos e prompts MCP, quando o servidor suporta
• Filtragem por servidor, para você expor só as ferramentas MCP que realmente quer que o Hermes veja

Início rápido

1. O suporte a MCP já vem na instalação padrão — nenhum passo extra é necessário.

2. Acrescente um servidor MCP ao ~/.hermes/config.yaml:

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/usuario/projetos"]

3. Suba o Hermes:

hermes chat

4. Peça ao Hermes que use a capacidade servida pelo MCP.

Por exemplo:

Liste os arquivos em /home/usuario/projetos e resuma a estrutura do repositório.

O Hermes vai descobrir as ferramentas do servidor MCP e usá-las como qualquer outra ferramenta.

Catálogo: instalação em um clique de MCPs aprovados pela Nous

O Hermes traz um catálogo curado de servidores MCP que a equipe da Nous revisou e mesclou. Eles vêm desligados por padrão — instale só o que você realmente quer.

hermes mcp                # seletor interativo (padrão)
hermes mcp catalog        # lista em texto puro, scriptável
hermes mcp install n8n    # instala uma entrada do catálogo pelo nome

O seletor mostra cada entrada com o status atual dela:

n8n          available              Manage and inspect n8n workflows from Hermes
linear       enabled                Linear issue/project management (remote OAuth)
github       installed (disabled)   GitHub repo + PR tools

Aperte Enter em uma linha para instalar (e passar por qualquer credencial exigida), habilitar, desabilitar ou desinstalar. As entradas do catálogo ficam em optional-mcps/, no repositório hermes-agent — estar naquele diretório significa aprovação da Nous. Não existe uma faixa de submissão da comunidade; as entradas entram por PR mesclado.

Entradas do catálogo podem exigir:

• Chave de API — o Hermes pergunta na hora da instalação e grava o valor em ~/.hermes/.env. Valores não secretos (URLs base) vão para o mesmo arquivo.
• OAuth (MCP remoto) — escrito como auth: oauth na sua configuração; o cliente MCP abre um navegador na primeira conexão.
• OAuth (provedor de terceiro, como Google/GitHub) — o Hermes te aponta para hermes auth <provedor> se você ainda não tiver se autenticado.

Seleção de ferramentas na hora da instalação

Depois de configurar as credenciais, o Hermes sonda o servidor MCP para listar cada ferramenta que ele expõe e apresenta uma lista de marcação:

Select tools for 'linear' (SPACE toggle, ENTER confirm)
  [x] find_issues       Find issues matching a query
  [x] get_issue         Get a single issue
  [x] create_issue      Create a new issue
  [ ] delete_workspace  Delete a Linear workspace
  ...

As linhas já marcadas vêm de:

1. A sua seleção anterior, se você já instalou esta entrada antes (reinstalações preservam o que você tinha — os padrões do manifesto não sobrescrevem isso)
2. O tools.default_enabled do manifesto, se a entrada declarar um (algumas entradas do catálogo já podam ferramentas que alteram estado ou que raramente servem)
3. Tudo, se nenhum dos dois se aplicar

Algumas entradas com superfícies autogeradas muito grandes (por exemplo, cloudflare, com cerca de 3.300 ferramentas de endpoint OpenAPI) declaram, em vez disso, tools.default_excluded — uma lista curada de bloqueio, com nomes e padrões glob. Instalar uma dessas pula a lista de marcação por completo e grava tools.exclude; tudo o que não bater continua habilitado, inclusive as ferramentas que o servidor acrescentar depois. Edite mcp_servers.<nome>.tools.exclude no config.yaml para reabilitar uma família.

Confirme a lista com ENTER. Só as ferramentas marcadas acabam em mcp_servers.<nome>.tools.include. Se você selecionar tudo, nenhum filtro é escrito (formato de configuração mais limpo, comportamento idêntico).

Se a sondagem falhar (servidor inalcançável, OAuth ainda não concluído, serviço de apoio fora do ar), a instalação ainda dá certo: o tools.default_enabled do manifesto é aplicado direto (se declarado), ou nenhum filtro é escrito (se não). Rode hermes mcp configure <nome> de novo quando o servidor estiver alcançável, para refinar.

Modelo de confiança

Instalar uma entrada do catálogo roda o que o manifesto mandar — git clone, os comandos de bootstrap da entrada (pip install, npm install etc.) e, no fim, o código do próprio servidor MCP. Os manifestos passam por revisão de PR no repositório hermes-agent, então a Nous revisou cada entrada antes de ela entrar — mas você ainda deve ler o manifesto antes de instalar, em especial o repositório do campo source:, os comandos de install.bootstrap: e qualquer invocação de transport.command:.

Os manifestos ficam em optional-mcps/<nome>/manifest.yaml no GitHub. O seletor também imprime a URL de source: do manifesto na hora da instalação, para você conferir rapidinho o repositório de origem. A página de MCP do painel web mostra o mesmo detalhe de cada entrada do catálogo — transporte, tipo de autenticação, a URL do endpoint (HTTP) ou comando + args (stdio), a origem/ref de instalação do git e os comandos de bootstrap, além das notas de configuração — com o source: renderizado como link clicável, para você inspecionar exatamente a que uma entrada se conecta ou o que ela roda antes de clicar em Install.

Compatibilidade de versão do manifesto

Os manifestos fixam um manifest_version. O catálogo é compatível com o futuro: se um PR acrescentar uma entrada com um manifest_version mais novo do que o Hermes instalado entende, o seletor mostra um aviso (⚠ '<name>' requires a newer Hermes) para aquela entrada, em vez de escondê-la em silêncio. Rode hermes update para instalar o Hermes mais recente quando vir isso.

Substituição de ${ENV_VAR} em tempo de execução

Dentro de transport.command, transport.args, transport.url e headers de uma entrada, os marcadores ${VAR} são resolvidos na hora de conectar ao servidor, a partir das variáveis de ambiente (que incluem tudo o que está em ~/.hermes/.env). Isso é útil quando uma entrada do catálogo quer referenciar um valor que o usuário configurou em outro lugar — por exemplo, ${HOME}/foo ou ${MY_PROVIDER_TOKEN}.

Variáveis de contexto no estilo do Cursor também são substituídas (com diferença entre maiúsculas e minúsculas): ${userHome} (diretório home), ${workspaceFolder} (raiz do espaço de trabalho da sessão), ${workspaceFolderBasename} e ${pathSeparator} / ${/} (o separador de caminho do sistema). Veja a referência de configuração do MCP para os detalhes.

Repare que isso é diferente do ${INSTALL_DIR} nos manifestos do catálogo, que é substituído na hora da instalação pelo caminho para onde o catálogo clonou o repositório da entrada.

Atualizar a seleção de ferramentas depois

hermes mcp configure linear

Reabre a mesma lista de marcação com a sua seleção atual já marcada. Use isso quando quiser mais ferramentas habilitadas, ou quando o servidor acrescentar ferramentas novas que você quer aderir.

Atualizar o manifesto do catálogo

Os MCPs nunca são atualizados sozinhos. Rode hermes mcp install <nome> de novo para atualizar depois de uma atualização do Hermes, se a versão de um manifesto mudou.

Para acrescentar um MCP ao catálogo, abra um PR contra optional-mcps/.

Metadados de sugestão (suggest:)

Um manifesto pode declarar um bloco suggest: opcional, com listas keywords: e/ou hosts:. As superfícies de interface (hoje, o compositor do aplicativo Desktop) usam isso para oferecer uma pílula "Add <servidor>" de um clique quando o seu rascunho menciona uma das palavras-chave como palavra inteira, ou contém um link colado cujo nome de host termina com um dos sufixos listados. É puramente consultivo — as instalações continuam passando pelos mesmos caminhos validados de catálogo/configuração — e a maioria das entradas remotas hospedadas (Atlassian, Sentry, Notion, Stripe, Vercel, Supabase e companhia) o declara.

O GitHub está de propósito fora do catálogo: o MCP hospedado dele exige que cada cliente traga o próprio aplicativo OAuth (o registro dinâmico genérico de cliente é rejeitado), e as skills github/* que vêm com o Hermes, tocando a CLI gh, são uma integração mais capaz. No Desktop, menções ao GitHub oferecem, em vez disso, a skill github-auth quando o gh ainda não está autenticado.

Dois tipos de servidor MCP

Servidores stdio

Servidores stdio rodam como subprocessos locais e conversam por stdin/stdout.

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"

Use servidores stdio quando:

• o servidor está instalado localmente
• você quer acesso de baixa latência a recursos locais
• você está seguindo uma documentação de servidor MCP que mostra command, args e env

Servidores HTTP

Servidores MCP HTTP são endpoints remotos aos quais o Hermes se conecta direto.

mcp_servers:
  remote_api:
    url: "https://mcp.example.com/mcp"
    headers:
      Authorization: "Bearer ***"

Use servidores HTTP quando:

• o servidor MCP está hospedado em outro lugar
• a sua organização expõe endpoints MCP internos
• você não quer que o Hermes crie um subprocesso local para aquela integração

Servidores HTTP autenticados por OAuth

A maioria dos servidores MCP hospedados (Cloudflare, Linear, Sentry, Atlassian, Asana, Figma, Stripe…) exige OAuth 2.1 em vez de um token bearer estático. Defina auth: oauth e o Hermes cuida da descoberta, da identificação de cliente, do PKCE, da troca de tokens, da renovação e da autenticação escalonada, via o SDK Python do MCP.

O Hermes se identifica com um Client ID Metadata Document nos servidores que aceitam um, e cai no Dynamic Client Registration nos que não aceitam. Os dois são automáticos; não há nada para configurar.

MCP remoto do Figma

O endpoint hospedado do Figma (https://mcp.figma.com/mcp) libera o Dynamic Client Registration por client_name exato — um "Hermes Agent" puro toma 403, enquanto "Claude Code" e "Codex" passam. O Hermes define sozinho oauth.client_name: "Claude Code" para mcp.figma.com, então instalar/entrar funciona sem truque especial:

mcp_servers:
  figma:
    url: "https://mcp.figma.com/mcp"
    auth: oauth

Ou: hermes mcp install figma e depois hermes mcp login figma.

mcp_servers:
  linear:
    url: "https://mcp.linear.app/mcp"
    auth: oauth

Na primeira conexão, o Hermes imprime uma URL de autorização, abre o seu navegador quando dá, e espera o retorno do OAuth em uma porta local de loopback. Os tokens ficam em cache em ~/.hermes/mcp-tokens/<servidor>.json, com permissões 0o600; as execuções seguintes os reaproveitam em silêncio até a renovação falhar.

Hosts remotos / sem interface. Quando o Hermes roda em uma máquina diferente da do seu navegador, o retorno de loopback não alcança o seu laptop. Dois jeitos de completar o fluxo:

• Colar de volta (sem preparação): em um terminal interativo, o Hermes imprime "Or paste the redirect URL here…" ao lado da URL de autorização. Abra a URL no navegador, aprove, copie a URL completa em que o navegador parou (o redirecionamento vai mostrar um erro de conexão — isso é esperado) e cole no prompt. Strings de consulta puras, como ?code=…&state=…, também funcionam.
• Encaminhamento de porta por SSH: ssh -N -L <porta>:127.0.0.1:<porta> usuario@host em um terminal separado, e depois deixe o redirecionamento fluir normalmente.
• Retorno via proxy (redirect_uri): quando um endpoint HTTPS público encaminha para o host (por exemplo, um Tailscale Funnel ou um proxy reverso apontado para a porta de retorno), defina oauth.redirect_uri e o redirecionamento do navegador chega ao Hermes sozinho — sem túnel nem colagem:

mcp_servers:
  myserver:
    url: "https://mcp.example.com/mcp"
    auth: oauth
    oauth:
      redirect_port: 8765                                # porta fixa para o proxy mirar
      redirect_uri: "https://oauth.example.ts.net/callback"

Para gateways totalmente sem interface (bot de mensagens, nenhum terminal interativo), a skill opcional mcp-oauth-remote-gateway guia o agente para completar o fluxo na mão e gravar os tokens onde o Hermes espera.

Armadilha — o WAF rejeita URIs de redirecionamento com 127.0.0.1. Alguns provedores põem um WAF na frente do servidor de autorização, e ele devolve 403 para qualquer requisição de autorização cuja string de consulta contenha um 127.0.0.1 literal (o AWS API Gateway da Reclaim.ai é um exemplo conhecido — toda tentativa devolve {"message":"Forbidden"} antes de chegar ao aplicativo OAuth). Defina oauth.redirect_host: localhost para usar http://localhost:<porta>/callback; o ouvinte de retorno continua ligado em 127.0.0.1 nos dois casos.

Veja OAuth por SSH / hosts remotos para o passo a passo completo, incluindo servidores sem DCR (o Slack, por exemplo), client_id/client_secret pré-registrados, personalização de escopo e reautenticação com hermes mcp login <servidor>.

Armadilha — provedores que não suportam registro automático (Google Drive, Atlassian). Alguns servidores rejeitam o passo de registro dinâmico de cliente (RFC 7591) em que o auth: oauth puro se apoia — o servidor oficial do Drive do Google (https://drivemcp.googleapis.com/mcp/v1) devolve um 400 Bad Request, então nenhum cliente OAuth é criado e nenhum token é obtido. O sintoma é sutil: esses servidores também servem tools/list sem autenticação, então o hermes mcp login consegue listar as ferramentas e parecer que deu certo, mas toda chamada de ferramenta de verdade estoura o tempo depois. O hermes mcp login agora detecta isso (ele confere se um token realmente caiu no disco) e te manda fornecer o seu próprio cliente OAuth. Crie um no console do provedor e acrescente à configuração:

mcp_servers:
  googledrive:
    url: "https://drivemcp.googleapis.com/mcp/v1"
    auth: oauth
    oauth:
      client_id: "<seu-client-id-de-oauth>"
      client_secret: "<seu-client-secret-de-oauth>"

Depois rode hermes mcp login googledrive — com o cliente pré-registrado, o Hermes pula o registro e roda o fluxo normal de autorização pelo navegador.

Armadilha — corrida no recarregamento automático da configuração. Quando você edita ~/.hermes/config.yaml de dentro de uma sessão do Hermes em execução, a CLI recarrega as conexões MCP com um tempo limite de 30s. Isso não basta para um fluxo OAuth interativo. Acrescente a entrada e depois rode hermes mcp login <servidor> de um terminal novo — ele espera os 5 minutos completos para você concluir a autenticação.

mTLS / certificados de cliente

Servidores MCP HTTP remotos que exigem TLS mútuo (autenticação por certificado de cliente) são suportados via client_cert / client_key. O Hermes passa o certificado resolvido para o cliente HTTP subjacente, para o aperto de mão TLS.

O client_cert aceita três formatos:

• Um único caminho PEM combinado — um arquivo com o certificado e a chave privada juntos:

mcp_servers:
  internal_api:
    url: "https://mcp.internal.example.com/mcp"
    client_cert: "~/.certs/mcp-client.pem"

• Uma dupla [cert, key] — certificado e chave em arquivos separados (equivalente a definir client_cert + client_key):

mcp_servers:
  internal_api:
    url: "https://mcp.internal.example.com/mcp"
    client_cert: ["~/.certs/mcp-client.crt", "~/.certs/mcp-client.key"]

• Uma trinca [cert, key, password] — quando a chave privada é criptografada, o terceiro elemento é a senha da chave:

mcp_servers:
  internal_api:
    url: "https://mcp.internal.example.com/mcp"
    client_cert: ["~/.certs/mcp-client.crt", "~/.certs/mcp-client.key", "${MCP_KEY_PASSWORD}"]

Você também pode manter o certificado e a chave totalmente separados, via client_cert (PEM combinado) mais um client_key explícito. Os caminhos aceitam expansão de ~; um arquivo faltando levanta um erro claro, com o escopo do servidor, em vez de uma falha opaca de aperto de mão TLS.

Cabeçalho de identidade por usuário

Servidores MCP HTTP/SSE remotos que ajustam o comportamento pela identidade de quem chama (limites de taxa por usuário, trilhas de auditoria, roteamento multi-inquilino) podem receber um cabeçalho de identidade em toda requisição, via identity_header:

mcp_servers:
  team_api:
    url: "https://mcp.team.example.com/mcp"
    identity_header:
      name: "X-User-Id"
      value_from: "static"   # "static" (padrão) ou "profile"
      value: "alice"         # obrigatório para static

• value_from: static envia o value literal do config.yaml.
• value_from: profile envia o nome do perfil ativo do Hermes, resolvido uma vez na hora de conectar — útil quando vários perfis de uma máquina falam com o mesmo servidor e ele precisa distinguir entre eles.

Uma entrada explícita no mapeamento headers do servidor com o mesmo nome (em qualquer caixa) sempre vence; o cabeçalho de identidade nunca sobrescreve a sua própria configuração de cabeçalho. Blocos identity_header inválidos geram aviso e são ignorados — eles nunca impedem o servidor de conectar. Em servidores stdio, a chave é ignorada com um aviso (transportes stdio não têm cabeçalhos).

Referência básica de configuração

O Hermes lê a configuração de MCP em ~/.hermes/config.yaml, sob mcp_servers.

Chaves comuns

Chave	Tipo	Significado
command	string	Executável de um servidor MCP stdio
args	lista	Argumentos do servidor stdio
env	mapeamento	Variáveis de ambiente passadas ao servidor stdio
url	string	Endpoint MCP HTTP
headers	mapeamento	Cabeçalhos HTTP para servidores remotos
client_cert	string | lista	Certificado de cliente para mTLS — um caminho PEM combinado, ou [cert, key] / [cert, key, password]
client_key	string	Caminho do PEM da chave privada do cliente (quando separado de client_cert)
identity_header	mapeamento	Cabeçalho opcional de identidade por usuário, para servidores HTTP/SSE — {name, value_from: static|profile, value}
timeout	número	Tempo limite de chamada de ferramenta
connect_timeout	número	Tempo limite da conexão inicial (também limita o aperto de mão initialize do MCP)
idle_timeout_seconds	número	Recicla um servidor stdio depois desta quantidade de segundos sem chamada de ferramenta (0 = nunca, padrão). O servidor reinicia de forma transparente na chamada seguinte.
max_lifetime_seconds	número	Recicla um servidor stdio depois desta idade total (0 = nunca, padrão). Reinicia de forma transparente no próximo uso.
enabled	booleano	Se false, o Hermes pula o servidor por completo
supports_parallel_tool_calls	booleano	Se true, as ferramentas deste servidor podem rodar em paralelo
tools	mapeamento	Filtragem de ferramentas e política de utilitários deste servidor

Exemplo stdio mínimo

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

Reciclar servidores stdio pesados de memória

Servidores MCP baseados em navegador (por exemplo, @playwright/mcp) mantêm um Chromium inteiro residente depois da primeira chamada de ferramenta — centenas de MB que nunca são liberados. Adira à reciclagem automática e o servidor é derrubado depois do limite de ociosidade/vida, e reiniciado de forma transparente na próxima vez que uma das ferramentas dele for chamada (as ferramentas ficam registradas o tempo todo):

mcp_servers:
  playwright:
    command: "npx"
    args: ["-y", "@playwright/mcp@latest", "--headless"]
    idle_timeout_seconds: 900     # recicla depois de 15 min sem chamada de ferramenta
    max_lifetime_seconds: 86400   # e pelo menos uma vez por dia, de todo jeito

Exemplo HTTP mínimo

mcp_servers:
  company_api:
    url: "https://mcp.internal.example.com"
    headers:
      Authorization: "Bearer ***"

Presets embutidos

Para servidores MCP conhecidos, o hermes mcp add aceita uma opção --preset que preenche os detalhes de transporte, para você não ter que caçar o comando e os argumentos. O preset só fornece os padrões — qualquer outra coisa (variáveis de ambiente, cabeçalhos, filtragem) que você passar na mesma linha de comando continua vencendo.

Preset	O que ele configura
codex	O servidor MCP da CLI do Codex (codex mcp-server por stdio). Exige a CLI codex no PATH.

# Adiciona a CLI do Codex como servidor MCP em uma linha
hermes mcp add codex --preset codex

Isso escreve o equivalente a:

mcp_servers:
  codex:
    command: "codex"
    args: ["mcp-server"]

Você pode escolher qualquer nome local (hermes mcp add my-codex --preset codex funciona); o preset só fornece os padrões de command/args.

Como o Hermes registra as ferramentas MCP

O Hermes prefixa as ferramentas MCP para que elas não colidam com nomes embutidos:

mcp_<server_name>_<tool_name>

Exemplos:

Servidor	Ferramenta MCP	Nome registrado
filesystem	read_file	mcp_filesystem_read_file
github	create-issue	mcp_github_create_issue
my-api	query.data	mcp_my_api_query_data

Na prática, você em geral não precisa chamar o nome prefixado na mão — o Hermes vê a ferramenta e a escolhe no raciocínio normal.

Higienização do resultado de ferramenta e _meta

Dois comportamentos valem para todo resultado de ferramenta MCP antes de o modelo o ver:

• Caracteres TAG invisíveis do Unicode são removidos. Os caracteres da faixa U+E0000–U+E007F não renderizam nada em terminais e interfaces de chat, mas são totalmente visíveis para o modelo — um canal clássico de contrabando de injeção de prompt para um servidor malicioso ou comprometido. O Hermes os remove dos resultados de ferramenta, do conteúdo de recursos e das descrições de ferramenta. Sequências legítimas de tag em emoji (bandeiras regionais, como 🏴󠁧󠁢󠁳󠁣󠁴󠁿) são preservadas.
• O _meta de fornecedor aparece; as chaves reservadas do protocolo, não. Quando um servidor anexa um mapeamento _meta a um resultado de ferramenta (espaços de nome de fornecedor, como com.example/handoff), o Hermes o repassa ao modelo junto com o conteúdo do resultado. As chaves sob prefixos reservados do protocolo — um rótulo modelcontextprotocol ou mcp seguido de outro rótulo, por exemplo modelcontextprotocol.io/... ou tools.mcp.com/... — são descartadas, seguindo as regras de nome de chave da especificação do MCP. Se não sobrar nada voltado ao modelo, o campo _meta é omitido por inteiro.

Ferramentas utilitárias do MCP

Quando há suporte, o Hermes também registra ferramentas utilitárias em torno dos recursos e prompts do MCP:

• list_resources
• read_resource
• list_prompts
• get_prompt

Elas são registradas por servidor, com o mesmo padrão de prefixo. Por exemplo:

• mcp_github_list_resources
• mcp_github_get_prompt

Importante

Essas ferramentas utilitárias agora levam em conta as capacidades:

• o Hermes só registra os utilitários de recurso se a sessão MCP realmente suporta operações de recurso
• o Hermes só registra os utilitários de prompt se a sessão MCP realmente suporta operações de prompt

Ou seja: um servidor que expõe ferramentas chamáveis, mas nenhum recurso/prompt, não ganha esses invólucros extras.

Filtragem por servidor

Você pode controlar quais ferramentas cada servidor MCP contribui ao Hermes, o que permite administrar o seu espaço de nomes de ferramentas com granularidade fina.

Desabilitar um servidor por completo

mcp_servers:
  legacy:
    url: "https://mcp.legacy.internal"
    enabled: false

Com enabled: false, o Hermes pula o servidor completamente e nem tenta uma conexão.

Lista de permissão de ferramentas do servidor

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
    tools:
      include: [create_issue, list_issues]

Só aquelas ferramentas do servidor MCP são registradas.

As entradas de include/exclude também podem ser padrões glob (*, ?, [...], com diferença entre maiúsculas e minúsculas): include: ["*_dns_*"] registra toda ferramenta cujo nome contenha _dns_. Entradas simples, sem metacaracteres, continuam sendo correspondência exata. Os globs são o jeito prático de filtrar servidores que expõem milhares de ferramentas de endpoint autogeradas, por família de produto.

Lista de bloqueio de ferramentas do servidor

mcp_servers:
  stripe:
    url: "https://mcp.stripe.com"
    tools:
      exclude: [delete_customer]

Todas as ferramentas do servidor são registradas, menos as excluídas.

Padrões glob

As duas listas aceitam globs no estilo fnmatch ao lado de nomes exatos — algo essencial em superfícies planas enormes, como o MCP da API da Cloudflare (?codemode=false, cerca de 3.300 ferramentas), em que excluir áreas de produto um endpoint por vez é inviável:

mcp_servers:
  cloudflare:
    url: "https://mcp.cloudflare.com/mcp?codemode=false"
    auth: oauth
    tools:
      exclude: ["*_radar_*", "*_accounts_dlp_*", "*_zones_web3_*"]

Entradas sem metacaracteres de glob (*, ?, [) correspondem exatamente — docs exclui só a ferramenta chamada docs, nunca docs_search.

Regra de precedência

Se os dois estiverem presentes:

tools:
  include: [create_issue]
  exclude: [create_issue, delete_issue]

O include vence.

Filtrar também as ferramentas utilitárias

Você também pode desabilitar à parte os invólucros utilitários que o Hermes acrescenta:

mcp_servers:
  docs:
    url: "https://mcp.docs.example.com"
    tools:
      prompts: false
      resources: false

Isso quer dizer:

• tools.resources: false desabilita list_resources e read_resource
• tools.prompts: false desabilita list_prompts e get_prompt

Exemplo completo

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
    tools:
      include: [create_issue, list_issues, search_code]
      prompts: false

  stripe:
    url: "https://mcp.stripe.com"
    headers:
      Authorization: "Bearer ***"
    tools:
      exclude: [delete_customer]
      resources: false

  legacy:
    url: "https://mcp.legacy.internal"
    enabled: false

O que acontece se tudo for filtrado?

Se a sua configuração filtrar todas as ferramentas chamáveis e desabilitar ou omitir todos os utilitários suportados, o Hermes não cria um conjunto de ferramentas MCP vazio em tempo de execução para aquele servidor.

Isso mantém a lista de ferramentas limpa.

Comportamento em tempo de execução

Hora da descoberta

O Hermes descobre os servidores MCP na inicialização e registra as ferramentas deles no registro normal de ferramentas.

Descoberta dinâmica de ferramentas

Os servidores MCP podem avisar o Hermes quando as ferramentas disponíveis mudam em tempo de execução, enviando uma notificação notifications/tools/list_changed. Quando o Hermes recebe essa notificação, ele busca de novo a lista de ferramentas do servidor automaticamente e atualiza o registro — sem precisar de /reload-mcp na mão.

Isso é útil para servidores MCP cujas capacidades mudam dinamicamente (por exemplo, um servidor que acrescenta ferramentas quando um novo esquema de banco é carregado, ou remove ferramentas quando um serviço sai do ar).

A atualização é protegida por trava, para que notificações em rajada do mesmo servidor não causem atualizações sobrepostas. As notificações de mudança de prompt e de recurso (prompts/list_changed, resources/list_changed) são recebidas, mas ainda não geram ação.

Recarregar

Se você mudar a configuração de MCP, use:

/reload-mcp

Isso recarrega os servidores MCP a partir da configuração e atualiza a lista de ferramentas disponíveis. Para mudanças de ferramenta em tempo de execução, empurradas pelo próprio servidor, veja Descoberta dinâmica de ferramentas, acima.

Conjuntos de ferramentas

Cada servidor MCP configurado também cria um conjunto de ferramentas em tempo de execução quando contribui pelo menos uma ferramenta registrada:

mcp-<server>

Isso deixa os servidores MCP mais fáceis de raciocinar no nível do conjunto de ferramentas.

Modelo de segurança

Filtragem de ambiente do stdio

Em servidores stdio, o Hermes não passa cegamente todo o seu ambiente de shell.

Só o env configurado explicitamente, mais uma base segura, é repassado. Isso reduz o vazamento acidental de segredos.

Controle de exposição no nível da configuração

O novo suporte a filtragem também é um controle de segurança:

• desabilite ferramentas perigosas que você não quer que o modelo veja
• exponha só uma lista de permissão mínima para um servidor sensível
• desabilite os invólucros de recurso/prompt quando não quiser aquela superfície exposta

Exemplos de caso de uso

Servidor do GitHub com uma superfície mínima de gestão de issues

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
    tools:
      include: [list_issues, create_issue, update_issue]
      prompts: false
      resources: false

Use assim:

Me mostre as issues abertas com a etiqueta bug e depois rascunhe uma issue nova sobre o comportamento instável de reconexão do MCP.

Servidor do Stripe com as ações perigosas removidas

mcp_servers:
  stripe:
    url: "https://mcp.stripe.com"
    headers:
      Authorization: "Bearer ***"
    tools:
      exclude: [delete_customer, refund_payment]

Use assim:

Procure os últimos 10 pagamentos que falharam e resuma os motivos comuns de falha.

Servidor de sistema de arquivos para uma única raiz de projeto

mcp_servers:
  project_fs:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/usuario/meu-projeto"]

Use assim:

Inspecione a raiz do projeto e explique o layout de diretórios.

Resolução de problemas

O servidor MCP não conecta

Confira:

# Verifique se as dependências de MCP estão instaladas (já vêm na instalação padrão)
cd ~/.hermes/hermes-agent && uv pip install -e ".[mcp]"

node --version
npx --version

Depois confira a sua configuração e reinicie o Hermes.

As ferramentas não aparecem

Causas possíveis:

• o servidor não conseguiu conectar
• a descoberta falhou
• a sua configuração de filtro excluiu as ferramentas
• a capacidade utilitária não existe naquele servidor
• o servidor está desabilitado com enabled: false

Se você está filtrando de propósito, isso é o esperado.

Por que os utilitários de recurso ou de prompt não apareceram?

Porque o Hermes agora só registra esses invólucros quando as duas coisas são verdadeiras:

1. a sua configuração permite
2. a sessão do servidor realmente suporta a capacidade

Isso é intencional e mantém a lista de ferramentas honesta.

Chamadas de ferramenta em paralelo

Por padrão, as ferramentas MCP rodam em sequência — uma de cada vez. Se o seu servidor MCP expõe ferramentas que são seguras para rodar em paralelo (por exemplo, consultas só de leitura, chamadas de API independentes), você pode aderir à execução paralela:

mcp_servers:
  docs:
    command: "docs-server"
    supports_parallel_tool_calls: true

Quando supports_parallel_tool_calls é true, o Hermes pode executar várias ferramentas daquele servidor ao mesmo tempo, dentro de um mesmo lote de chamadas, igual ao que faz com as ferramentas embutidas só de leitura (web_search, read_file etc.).

cuidado

Só habilite chamadas em paralelo para servidores MCP cujas ferramentas sejam seguras para rodar ao mesmo tempo. Se as ferramentas leem e escrevem estado compartilhado, arquivos, bancos de dados ou recursos externos, revise as condições de corrida de leitura/escrita antes de ligar essa configuração.

Suporte a sampling do MCP

Os servidores MCP podem pedir inferência de LLM ao Hermes pelo protocolo sampling/createMessage. Isso permite que um servidor MCP peça ao Hermes que gere texto em nome dele — útil para servidores que precisam de capacidades de LLM, mas não têm acesso a um modelo próprio.

O sampling vem habilitado por padrão para todos os servidores MCP (quando o SDK do MCP suporta). Configure por servidor, sob a chave sampling:

mcp_servers:
  my_server:
    command: "my-mcp-server"
    sampling:
      enabled: true            # Habilita o sampling (padrão: true)
      model: "openai/gpt-4o"  # Sobrescreve o modelo das requisições de sampling (opcional)
      max_tokens_cap: 4096     # Máximo de tokens por resposta de sampling (padrão: 4096)
      timeout: 30              # Tempo limite em segundos por requisição (padrão: 30)
      max_rpm: 10              # Limite de taxa: máximo de requisições por minuto (padrão: 10)
      max_tool_rounds: 5       # Máximo de rodadas de uso de ferramenta nos laços de sampling (padrão: 5)
      allowed_models: []       # Lista de permissão de modelos que o servidor pode pedir (vazia = qualquer um)
      log_level: "info"        # Nível do log de auditoria: debug, info ou warning (padrão: info)

O tratador de sampling inclui um limitador de taxa por janela deslizante, tempos limite por requisição e limites de profundidade no laço de ferramentas, para evitar uso descontrolado. As métricas (contagem de requisições, erros, tokens usados) são acompanhadas por instância de servidor.

Para desabilitar o sampling em um servidor específico:

mcp_servers:
  untrusted_server:
    url: "https://mcp.example.com"
    sampling:
      enabled: false

Suporte a elicitação do MCP

Os servidores MCP podem pedir uma entrada estruturada ao usuário no meio de uma chamada de ferramenta, pelo protocolo elicitation/create (SDK Python do mcp ≥ 1.11.0). O Hermes roteia as elicitações em modo formulário pela superfície de aprovação que já existe — um prompt interativo na CLI/TUI, ou botões de aprovação em plataformas de gateway como Telegram e Slack — para que a requisição te alcance onde quer que a sessão viva. As elicitações em modo URL (em que um servidor te aponta para uma URL externa) são recusadas como não suportadas.

A elicitação vem habilitada por padrão em cada servidor. Configure sob a chave elicitation:

mcp_servers:
  my_server:
    command: "my-mcp-server"
    elicitation:
      enabled: true    # padrão: true
      timeout: 300     # segundos de espera pela sua resposta (padrão: 300)

O tempo limite padrão de 5 minutos espelha o padrão de aprovação do gateway, para que quem está em superfícies assíncronas tenha tempo de responder antes de o servidor desistir. As métricas por servidor (requisições, aceitas, recusadas, erros) são acompanhadas no tratador.

Rodar o Hermes como servidor MCP

Além de se conectar a servidores MCP, o Hermes também pode ser um servidor MCP. Isso deixa outros agentes com suporte a MCP (Claude Code, Cursor, Codex ou qualquer cliente MCP) usarem as capacidades de mensagem do Hermes — listar conversas, ler o histórico de mensagens e enviar mensagens por todas as suas plataformas conectadas.

Quando usar isso

• Você quer que o Claude Code, o Cursor ou outro agente de programação envie e leia mensagens de Telegram/Discord/Slack pelo Hermes
• Você quer um único servidor MCP que faça a ponte com todas as plataformas de mensagem conectadas ao Hermes de uma vez
• Você já tem um gateway do Hermes rodando, com plataformas conectadas

Início rápido

hermes mcp serve

Isso sobe um servidor MCP stdio. Quem administra o ciclo de vida do processo é o cliente MCP, não você.

Configuração do cliente MCP

Acrescente o Hermes à configuração do seu cliente MCP. Por exemplo, no ~/.claude/claude_desktop_config.json do Claude Code:

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

Ou, se você instalou o Hermes em um local específico:

{
  "mcpServers": {
    "hermes": {
      "command": "/home/usuario/.hermes/hermes-agent/venv/bin/hermes",
      "args": ["mcp", "serve"]
    }
  }
}

Ferramentas disponíveis

O servidor MCP expõe 10 ferramentas, equivalentes à superfície de ponte de canais do OpenClaw mais um navegador de canais específico do Hermes:

Ferramenta	Descrição
conversations_list	Lista as conversas de mensagem ativas. Filtre por plataforma ou busque por nome.
conversation_get	Traz informação detalhada de uma conversa, pela chave de sessão.
messages_read	Lê o histórico recente de mensagens de uma conversa.
attachments_fetch	Extrai anexos não textuais (imagens, mídia) de uma mensagem específica.
events_poll	Consulta novos eventos de conversa a partir de uma posição de cursor.
events_wait	Consulta longa / bloqueia até o próximo evento chegar (quase em tempo real).
messages_send	Envia uma mensagem por uma plataforma (por exemplo, telegram:123456, discord:#general).
channels_list	Lista os destinos de mensagem disponíveis em todas as plataformas.
permissions_list_open	Lista os pedidos de aprovação pendentes vistos nesta sessão de ponte.
permissions_respond	Permite ou nega um pedido de aprovação pendente.

Sistema de eventos

O servidor MCP inclui uma ponte de eventos ao vivo, que consulta o banco de sessões do Hermes em busca de mensagens novas. Isso dá aos clientes MCP uma consciência quase em tempo real das conversas que chegam:

# Consulta eventos novos (não bloqueia)
events_poll(after_cursor=0)

# Espera o próximo evento (bloqueia até o tempo limite)
events_wait(after_cursor=42, timeout_ms=30000)

Tipos de evento: message, approval_requested, approval_resolved

A fila de eventos fica em memória e começa quando a ponte conecta. Mensagens mais antigas ficam disponíveis por messages_read.

Opções

hermes mcp serve              # Modo normal
hermes mcp serve --verbose    # Log de depuração no stderr

Como funciona

O servidor MCP lê os dados de conversa direto do repositório de sessões do Hermes — o ~/.hermes/state.db é a fonte principal, com o sessions.json mantido só como fallback legado. Uma thread em segundo plano consulta o banco em busca de mensagens novas e mantém uma fila de eventos em memória. Para enviar mensagens, ele usa o mesmo motor interno de envio (tools/send_message_tool.py) que move a entrega do cron e a CLI hermes send.

O gateway NÃO precisa estar rodando para as operações de leitura (listar conversas, ler histórico, consultar eventos). Ele PRECISA estar rodando para as operações de envio, já que os adaptadores de plataforma precisam de conexões ativas.

Limites atuais

• O hermes mcp serve embutido expõe hoje um servidor MCP só stdio. Se você precisa de um servidor MCP HTTP, rode um adaptador separado — ou, muito mais comum, use o lado cliente do MCP no Hermes, que já fala stdio e HTTP (url + headers em mcp_servers.yaml / config.yaml; veja Servidores HTTP, acima).
• Consulta de eventos em intervalos de cerca de 200ms, com consulta ao banco otimizada por mtime (pula trabalho quando os arquivos não mudaram)
• Ainda sem o protocolo de notificação por push claude/channel
• Envios só de texto (sem envio de mídia/anexo por messages_send)

Documentação relacionada

• Usar MCP com o Hermes
• Comandos da CLI
• Comandos de barra
• FAQ

---