Pular para o conteúdo principal

Documentação oficial desta página · v0.20.6

Usar MCP com o Hermes

Este guia mostra como de fato usar MCP com o Hermes Agent no fluxo do dia a dia.

Se a página do recurso explica o que é MCP, este guia é sobre como extrair valor dele rápido e com segurança.

Quando você deve usar MCP?​

Use MCP quando:

  • uma ferramenta já existe em forma de MCP e você não quer construir uma ferramenta nativa do Hermes
  • você quer que o Hermes opere contra um sistema local ou remoto por uma camada de RPC limpa
  • você quer controle fino da exposição de cada servidor
  • você quer conectar o Hermes a APIs internas, bancos de dados ou sistemas da empresa sem modificar o núcleo do Hermes

Não use MCP quando:

  • uma ferramenta embutida do Hermes já resolve bem o trabalho
  • o servidor expõe uma superfície de ferramentas enorme e perigosa e você não está preparado para filtrar
  • você só precisa de uma integração bem estreita e uma ferramenta nativa seria mais simples e mais segura

Modelo mental​

Pense no MCP como uma camada de adaptação:

  • o Hermes continua sendo o agente
  • os servidores MCP contribuem com ferramentas
  • o Hermes descobre essas ferramentas na partida ou na hora do recarregamento
  • o modelo pode usá-las como ferramentas normais
  • você controla quanto de cada servidor fica visível

Essa última parte importa. Bom uso de MCP não é só "conectar tudo". É "conectar a coisa certa, com a menor superfície útil".

Passo 1: instale o suporte a MCP​

Se você instalou o Hermes com o script de instalação padrão, o suporte a MCP já vem incluído (o instalador roda uv pip install -e ".[all]").

Se você instalou sem os extras e precisa acrescentar o MCP separadamente:

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

Para servidores baseados em npm, garanta que o Node.js e o npx estão disponíveis.

Para muitos servidores MCP em Python, o uvx é um padrão agradável.

Passo 2: acrescente um servidor primeiro​

Comece com um servidor único e seguro.

Exemplo: acesso ao sistema de arquivos de um único diretório de projeto.

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

Depois inicie o Hermes:

hermes chat

Agora peça algo concreto:

Inspecione este projeto e resuma o layout do repositório.

Passo 3: verifique se o MCP carregou​

Você pode verificar o MCP de algumas formas:

  • o banner/estado do Hermes deve mostrar a integração MCP quando ela está configurada
  • pergunte ao Hermes quais ferramentas ele tem disponíveis
  • use /reload-mcp depois de mudanças na configuração
  • confira os logs se o servidor não conseguiu conectar

Um prompt prático de teste:

Me diga quais ferramentas apoiadas por MCP estão disponíveis agora.

Passo 4: comece a filtrar imediatamente​

Não deixe para depois se o servidor expõe muitas ferramentas.

Exemplo: permita na lista só o que você quer​

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

Este costuma ser o melhor padrão para sistemas sensíveis.

WSL2: ligue o Hermes no WSL ao Chrome do Windows​

Esta é a configuração prática quando:

  • o Hermes roda dentro do WSL2
  • o navegador que você quer controlar é o seu Chrome normal, já logado, no Windows
  • o /browser connect fica desajeitado ou pouco confiável a partir do WSL

Nesta configuração, o Hermes não conecta no Chrome diretamente. Em vez disso:

  • o Hermes roda no WSL
  • o Hermes sobe um servidor MCP local por stdio
  • esse servidor MCP é lançado pela interoperabilidade com o Windows (cmd.exe ou powershell.exe)
  • o servidor MCP se acopla à sua sessão viva do Chrome no Windows

Modelo mental:

Hermes (WSL) -> ponte MCP por stdio -> Chrome do Windows

Por que este modo é útil​

  • você mantém o seu perfil real de navegador do Windows, com cookies e logins
  • o Hermes fica no ambiente Unix que ele suporta (WSL2)
  • o controle do navegador é exposto como ferramentas MCP, em vez de depender do transporte de navegador do núcleo do Hermes

Use o chrome-devtools-mcp.

Se o seu Chrome do Windows já tem a depuração remota viva habilitada em chrome://inspect/#remote-debugging, acrescente assim, a partir do WSL:

hermes mcp add chrome-devtools-win --command cmd.exe --args /c npx -y chrome-devtools-mcp@latest --autoConnect --no-usage-statistics

Depois de salvar o servidor:

hermes mcp test chrome-devtools-win

Então comece uma sessão nova do Hermes ou rode:

/reload-mcp

Prompt típico​

Uma vez carregado, o Hermes pode usar direto as ferramentas de navegador com prefixo de MCP. Por exemplo:

Chame a ferramenta MCP mcp_chrome_devtools_win_list_pages e liste as abas atuais do navegador.

Quando o /browser connect é a ferramenta errada​

Se o Hermes roda no WSL e o Chrome roda no Windows, o /browser connect pode falhar mesmo com o Chrome aberto e depurável.

Motivos comuns:

  • o WSL não consegue alcançar o mesmo endpoint local de host que o Chrome expõe para as ferramentas do Windows
  • os fluxos mais novos de depuração viva do Chrome não são iguais a um clássico ws://localhost:9222
  • é mais fácil se acoplar ao navegador a partir de um auxiliar do lado do Windows, como o chrome-devtools-mcp

Nesses casos, guarde o /browser connect para configurações no mesmo ambiente e use MCP para a ponte de navegador do WSL para o Windows.

Armadilhas conhecidas​

  • Inicie o Hermes de um caminho montado do Windows, como /mnt/c/Users/<voce> ou /mnt/c/workspace/..., quando estiver usando executáveis stdio do Windows via MCP.
  • Se você inicia o Hermes de /root ou de /home/..., o Windows pode emitir um aviso de diretório atual UNC antes de o servidor MCP subir.
  • Se o chrome-devtools-mcp --autoConnect estoura o tempo enquanto enumera páginas, reduza as abas de fundo/congeladas no Chrome e tente de novo.

Exemplo: bloqueie ações perigosas​

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

Exemplo: desligue também os invólucros utilitários​

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

O que a filtragem afeta, na prática?​

Existem duas categorias de funcionalidade exposta por MCP no Hermes:

  1. Ferramentas MCP nativas do servidor
  • filtradas com:
    • tools.include
    • tools.exclude
  1. Invólucros utilitários acrescentados pelo Hermes
  • filtrados com:
    • tools.resources
    • tools.prompts

Invólucros utilitários que você pode ver​

Recursos:

  • list_resources
  • read_resource

Prompts:

  • list_prompts
  • get_prompt

Esses invólucros só aparecem se:

  • a sua configuração os permite, e
  • a sessão do servidor MCP realmente suporta essas capacidades

Então o Hermes não vai fingir que um servidor tem recursos/prompts se ele não tem.

Padrões comuns​

Padrão 1: assistente de projeto local​

Use MCP para um servidor de sistema de arquivos ou de git local ao repositório quando você quer que o Hermes raciocine sobre um espaço de trabalho delimitado.

mcp_servers:
  fs:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projeto"]

  git:
    command: "uvx"
    args: ["mcp-server-git", "--repository", "/home/user/projeto"]

Bons prompts:

Revise a estrutura do projeto e identifique onde fica a configuração.
Confira o estado local do git e resuma o que mudou recentemente.

Padrão 2: registro de trabalho nativo do repositório com o Open Scaffold​

Use o Open Scaffold quando você quer que o Hermes leia o registro durável de trabalho de IA de um repositório: missão, planos, notas de evidência, pacotes de passagem e resultados de revisão/portão. O Hermes continua sendo o agente; o Open Scaffold continua sendo o registro local do repositório.

Acrescente o servidor para um repositório com o scaffold montado:

hermes mcp add open_scaffold --command npx --args -y open-scaffold@latest mcp serve --repo /caminho/absoluto/do/repo
hermes mcp test open_scaffold

Depois mantenha a superfície exposta voltada para leitura. Escolha select na pergunta do hermes mcp add, ou edite o config.yaml depois:

mcp_servers:
  open_scaffold:
    command: "npx"
    args: ["-y", "open-scaffold@latest", "mcp", "serve", "--repo", "/caminho/absoluto/do/repo"]
    tools:
      include:
        - list_plans
        - get_plan
        - get_mission
        - list_evidence
        - get_evidence
        - get_status
        - search_plans
        - list_amendments
        - get_handoff
        - analyze_loop
        - gate_loop
      prompts: false

Bons prompts:

Use as ferramentas MCP do Open Scaffold para compilar o pacote de passagem atual e me diga qual é a próxima ação permitida.
Inspecione os planos ativos e as notas de evidência, e depois diga se este repositório está pronto para revisão humana ou precisa de outra tentativa.

Notas de fronteira:

  • O MCP do Open Scaffold é local em primeiro lugar e somente leitura por padrão.
  • As ferramentas de escrita dele exigem que o servidor tenha subido com --allow-write; não habilite isso até você querer explicitamente que o Hermes altere arquivos .osc.
  • O Open Scaffold registra e faz o controle de portão do trabalho; ele não autoriza o Hermes a mesclar, publicar, implantar ou subir runtimes.
  • Fixe open-scaffold@<versão> em vez de @latest se você precisa de esquemas de ferramenta reproduzíveis.

Padrão 3: assistente de triagem no GitHub​

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

Bons prompts:

Liste as issues abertas sobre MCP, agrupe por tema e escreva uma issue de alta qualidade para o bug mais comum.
Busque no repositório os usos de _discover_and_register_server e explique como as ferramentas MCP são registradas.

Padrão 4: assistente de API interna​

mcp_servers:
  internal_api:
    url: "https://mcp.internal.example.com"
    headers:
      Authorization: "Bearer ***"
    tools:
      include: [list_customers, get_customer, list_invoices]
      resources: false
      prompts: false

Bons prompts:

Procure o cliente ACME Corp e resuma a atividade recente de faturas.

Este é o tipo de lugar em que uma lista estrita de permitidos é muito melhor que uma lista de exclusão.

Padrão 4: servidores de documentação / conhecimento​

Alguns servidores MCP expõem prompts ou recursos que se parecem mais com ativos de conhecimento compartilhado que com ações diretas.

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

Bons prompts:

Liste os recursos MCP disponíveis no servidor de documentação, depois leia o guia de integração e resuma.
Liste os prompts expostos pelo servidor de documentação e me diga quais ajudariam na resposta a incidentes.

Tutorial: configuração de ponta a ponta com filtragem​

Aqui vai uma progressão prática.

Fase 1: acrescente o MCP do GitHub com uma lista de permitidos apertada​

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

Inicie o Hermes e peça:

Busque na base de código as referências a MCP e resuma os principais pontos de integração.

Fase 2: expanda só quando precisar​

Se depois você também precisar atualizar issues:

tools:
  include: [list_issues, create_issue, update_issue, search_code]

Depois recarregue:

/reload-mcp

Fase 3: acrescente um segundo servidor com outra política​

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

  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projeto"]

Agora o Hermes pode combinar os dois:

Inspecione os arquivos do projeto local e depois crie uma issue no GitHub resumindo o bug que você encontrar.

É aí que o MCP fica poderoso: fluxos entre vários sistemas sem mudar o núcleo do Hermes.

Recomendações de uso seguro​

Prefira listas de permitidos para sistemas perigosos​

Para qualquer coisa financeira, voltada para o cliente ou destrutiva:

  • use tools.include
  • comece com o menor conjunto possível

Desligue os utilitários que você não usa​

Se você não quer o modelo navegando pelos recursos/prompts que o servidor oferece, desligue:

tools:
  resources: false
  prompts: false

Mantenha os servidores com escopo estreito​

Exemplos:

  • servidor de sistema de arquivos com raiz num único diretório de projeto, não no seu diretório pessoal inteiro
  • servidor de git apontado para um único repositório
  • servidor de API interna com exposição de ferramentas voltada para leitura por padrão

Recarregue depois de mudanças na configuração​

/reload-mcp

Faça isso depois de mudar:

  • listas de include/exclude
  • flags de habilitação
  • interruptores de resources/prompts
  • cabeçalhos de autenticação / variáveis de ambiente

Diagnóstico por sintoma​

"O servidor conecta, mas as ferramentas que eu esperava não estão lá"​

Causas possíveis:

  • filtradas pelo tools.include
  • excluídas pelo tools.exclude
  • invólucros utilitários desligados por resources: false ou prompts: false
  • o servidor não suporta recursos/prompts de verdade

"O servidor está configurado, mas nada carrega"​

Confira:

  • se não sobrou um enabled: false na configuração
  • se o comando/runtime existe (npx, uvx etc.)
  • se o endpoint HTTP está alcançável
  • se as variáveis de ambiente ou os cabeçalhos de autenticação estão certos

"Por que eu vejo menos ferramentas do que o servidor MCP anuncia?"​

Porque o Hermes agora respeita a sua política por servidor e faz o registro ciente das capacidades. Isso é esperado, e em geral desejável.

"Como eu removo um servidor MCP sem apagar a configuração?"​

Use:

enabled: false

Isso mantém a configuração ali, mas impede a conexão e o registro.

Bons primeiros servidores para a maioria das pessoas:

  • sistema de arquivos
  • git
  • GitHub
  • servidores MCP de fetch / documentação
  • uma API interna bem estreita

Primeiros servidores nada bons:

  • sistemas de negócio gigantes, com muitas ações destrutivas e sem filtragem
  • qualquer coisa que você não entende bem o suficiente para restringir