Pular para o conteúdo principal

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

Gerenciar o Hermes Cloud com MCP

O Hermes Cloud roda instâncias hospedadas do Hermes Agent para você. Normalmente você as gerencia pela página /agents do Nous Portal. Este guia conecta o seu Hermes Agent local ao servidor MCP do Portal, para você gerenciar essas instâncias na nuvem só pedindo — "liste meus agentes na nuvem", "reinicie o que está parado", "quanto isso está me custando" — sem sair do terminal.

É um servidor MCP comum, hospedado pela Nous Research, protegido pelo mesmo login OAuth que você já usa no Portal. Uma vez conectado, o Hermes ganha duas ferramentas que pode chamar em seu nome.

O que dá para fazer com isso​

Depois de conectado, o modelo pode chamar estas ações na sua organização do Hermes Cloud:

Você pede…O que roda por baixo
"Liste meus agentes na nuvem"agents (list)
"Qual é o status de <nome>?"agents (get / status)
"Quanto essa instância está custando, mais ou menos?"agents (cost_estimate)
"Inicie / pare / reinicie <nome>"agent (start / stop / restart)
"Suba uma instância nova chamada <nome>"agent (create)
"Destrua <nome>"agent (destroy)
"Atualize o env / a imagem de <nome>"agent (update_env / update_image)

Toda chamada roda contra a sua organização, com a sua identidade do Portal, e a participação é reconferida a cada chamada — a conexão só consegue mexer nas instâncias que você já controla pela interface web.

Pré-requisitos​

  • Uma conta no Nous Portal com acesso ao Hermes Cloud (pelo menos uma instância, ou permissão para criar uma).

  • Suporte a MCP instalado. Se você usou o script de instalação padrão, já está lá; caso contrário:

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

Você não precisa de uma chave de API separada nem de client secret — o servidor usa OAuth com PKCE, e o login é uma ida e volta pelo navegador.

Passo 1: adicione o servidor​

hermes mcp add --url https://portal.nousresearch.com/mcp --auth oauth hermes-cloud

O --auth oauth diz ao Hermes que este é um servidor HTTP protegido por OAuth. Na primeira conexão, o Hermes:

  1. Descobre automaticamente os endpoints OAuth do servidor (metadados RFC 9728 / 8414).
  2. Registra-se como cliente (Dynamic Client Registration, RFC 7591) — nenhum segredo para copiar.
  3. Abre o navegador no Portal para você entrar e autorizar.
  4. Guarda o token resultante em ~/.hermes/mcp-tokens/ e o reutiliza (a renovação é automática).

Escolher uma organização​

Se a sua conta do Portal pertence a mais de uma organização, o navegador mostra um seletor de organização durante a autorização — escolha qual organização esta conexão deve gerenciar. A escolha é feita uma vez, no navegador; não há nada para passar na linha de comando. Contas com uma organização só pulam esse passo e vinculam automaticamente.

Se algum dia você precisar apontar a conexão para outra organização, remova e adicione o servidor de novo (hermes mcp remove hermes-cloud e depois o comando add outra vez) e escolha a outra organização no navegador.

Passo 2: confirme a conexão​

hermes mcp test hermes-cloud

Depois inicie (ou recarregue) uma sessão:

hermes chat
/reload-mcp

Faça uma pergunta somente de leitura para confirmar que as ferramentas estão ativas:

Liste meus agentes do Hermes Cloud e o status atual de cada um.

Você deve receber de volta as mesmas instâncias que vê na página /agents do Portal.

Passo 3: use​

Perguntas somente de leitura são sempre seguras:

Quais dos meus agentes na nuvem estão rodando agora e quanto cada um está custando, aproximadamente?

As ações de ciclo de vida viram pedidos comuns:

Reinicie a instância chamada research-bot.
Crie uma instância nova do Hermes Cloud chamada scratch e me avise quando estiver pronta.

O Hermes relata o que cada ferramenta retornou — a lista de instâncias, o novo status, os detalhes da instância criada — para você confirmar que a ação surtiu efeito.

Configuração​

Depois do hermes mcp add, o servidor fica em ~/.hermes/config.yaml:

mcp_servers:
  hermes-cloud:
    url: "https://portal.nousresearch.com/mcp"
    auth: oauth

Nenhuma credencial vai para o config.yaml — o token OAuth é guardado à parte, em ~/.hermes/mcp-tokens/, do mesmo jeito que o refresh token do Portal fica fora da sua configuração.

Limitar a superfície de ferramentas​

O servidor expõe tanto a ferramenta de leitura (agents) quanto a de escrita (agent). Se você quer que a conexão seja somente leitura — listar e inspecionar, mas nunca iniciar/parar/criar/destruir —, restrinja-a à ferramenta agents:

mcp_servers:
  hermes-cloud:
    url: "https://portal.nousresearch.com/mcp"
    auth: oauth
    tools:
      include: [agents]

Rode /reload-mcp depois de mudar a configuração. Veja Usar MCP com o Hermes para o modelo completo de filtragem (include/exclude, prompts, resources).

Solução de problemas​

O navegador mostra um seletor de organização e não sei qual escolher​

Você pertence a várias organizações no Portal. Escolha aquela cujas instâncias do Hermes Cloud você quer gerenciar por esta conexão. Na dúvida, é a organização dona das instâncias que aparecem na página /agents do Portal. Dá para escolher de novo depois, removendo e adicionando o servidor outra vez.

"invalid_client" ou "unknown client" na conexão​

O registro de cliente guardado não bate mais com o servidor (por exemplo, você se conectou a outro ambiente antes). Limpe o estado OAuth em cache deste servidor e adicione-o de novo:

hermes mcp remove hermes-cloud
rm -f ~/.hermes/mcp-tokens/hermes-cloud.*
hermes mcp add --url https://portal.nousresearch.com/mcp --auth oauth hermes-cloud

As ferramentas não aparecem depois de adicionar o servidor​

Recarregue o MCP dentro da sessão e confira de novo:

/reload-mcp
Me diga quais ferramentas vindas de MCP estão disponíveis agora.

Se ainda faltarem, rode hermes mcp test hermes-cloud para ver o erro de conexão diretamente.

Ele pede para eu entrar de novo​

Os tokens OAuth se renovam sozinhos, mas se o Portal invalidar a sua sessão (troca de senha, revogação, expiração) a próxima chamada pede uma nova autorização. Rode o comando hermes mcp add de novo — o fluxo no navegador gera um token novo.

Máquina sem interface gráfica / SSH / host remoto​

O callback OAuth do navegador roda na máquina onde o Hermes está rodando. Em um host remoto, encaminhe a porta de loopback por SSH — o mesmo padrão de qualquer outro login OAuth. Veja OAuth por SSH / hosts remotos.

Veja também​