Hermes Agent para Freshdesk: como conectar com segurança (2026)

Por que olhei o Hermes no Freshdesk

Meu trabalho diário na eesel é construir integrações, e a API do Freshdesk é uma em que já passei tempo suficiente para ter opiniões sobre seus limites de taxa. A eesel roda IA em filas de suporte reais há anos, e a mesma lição volta sempre: o modelo é a parte fácil. O difícil é decidir no que a IA pode mexer e saber que ela está pronta antes que algum cliente seja o primeiro a descobrir que não está.

O Hermes Agent é o agente de código aberto e auto-hospedado da Nous Research, com 251.479 estrelas no GitHub sob licença MIT. A pergunta geral eu já trabalhei em Hermes Agent for customer support. O que você está lendo agora é a versão para Freshdesk, e ela precisava de um post próprio porque o Freshdesk mudou a resposta no mês passado.

Vale dizer logo de início que o Hermes não traz nada específico do Freshdesk. Seu catálogo selecionado de 68 servidores MCP não tem entrada do Freshdesk, e quando pesquisei no Hacker News, Reddit e X, ninguém descrevia uma configuração de Hermes com Freshdesk também. Então tudo abaixo eu montei a partir da documentação dos dois fornecedores, que é mais ou menos como você teria de construir por conta própria de qualquer forma.

O que mudou: o Freshdesk agora tem seu próprio servidor MCP

Até pouco tempo atrás, se você queria um agente externo no Freshdesk, era código da comunidade ou um wrapper que você mesmo escrevia em torno da API v2 do Freshdesk. Agora o Freshdesk mantém um servidor próprio. Segundo o artigo sobre MCP, "Starting September 10, 2026, the Freshworks MCP integration is generally available."

Os principais fatos, todos vindos das FAQs de MCP do Freshdesk e desse mesmo artigo:

• Planos: Growth, Pro e Enterprise, apenas nas versões 2021 Standalone ou Omni 2026. Contas legadas não são suportadas.
• Endpoint: https://<subdomain>.freshdesk.com/mcp. Domínios personalizados não funcionam.
• Autenticação: apenas chave de API, e as chamadas seguem as permissões de papel daquele usuário.
• Ferramentas: 37, cobrindo tickets, conversas, contatos, agentes, grupos, empresas e artigos da central de ajuda. Sem ferramentas de exclusão ou mesclagem.
• Ativado por padrão. Um administrador pode desligá-lo em Admin Settings > Apps & Integrations > MCP.

Ele também é medido por uso, e isso é novo no Freshdesk. O item aparece em cada cartão de plano:

O Freshdesk documenta Claude Code, Claude Desktop, Cursor, Copilot Studio e VS Code como clientes, e acrescenta que "any AI tool that provides MCP support" funciona. Como o Hermes fala MCP sobre HTTP, ele se enquadra. Para quem já leu meu post Claude for Freshdesk, é o mesmo servidor, agora fora do acesso antecipado e disponível em planos mais baratos.

Quatro formas de conectar o Hermes ao Freshdesk

Abaixo estão todos os caminhos que encontrei, e quem revisou o código que acaba guardando sua chave de API:

Hoje eu escolheria o primeiro. O fornecedor cujos dados ele toca é quem o mantém, e suas credenciais do helpdesk não fazem um desvio por terceiros. Ele também cobre artigos da central de ajuda, o que o servidor da effytech não faz (não tem ferramentas de artigos de soluções). Quanto ao caminho do webhook, é menos uma quarta alternativa e mais um gatilho: ele avisa o Hermes de que chegou um ticket, e o Hermes ainda precisa de um dos outros três para realmente lê-lo ou escrever nele.

Como configurar com segurança

Esta é a ordem que eu seguiria. A maioria destes passos só existe por causa de uma única frase na FAQ do Freshdesk: "tool-level access management is not available. All supported MCP tools are available by default to any user who connects using a valid API key."

1. Dê ao Hermes sua própria vaga de agente

O servidor MCP age como o agente a quem a chave de API pertence. Cole a sua própria chave e o Hermes poderá fazer tudo o que você pode, com cada nota que escrever parecendo escrita por você.

O que eu faria é criar um agente dedicado para o bot, dar a ele um papel restrito e chamá-lo de algo como "Hermes (draft only)". No Freshdesk isso significa uma vaga paga, a partir de US$ 19/agente/mês no Growth com cobrança anual. De tudo nesta configuração, é o recurso de segurança mais barato, já que as permissões de papel são o único limite que o Freshdesk aplica do lado do servidor.

2. Adicione o servidor e filtre suas ferramentas

O Hermes guarda os servidores MCP em mcp_servers no ~/.hermes/config.yaml e resolve marcadores ${VAR} a partir de ~/.hermes/.env. Ele também permite criar uma lista de permissões de ferramentas por servidor (documentação MCP do Hermes). Juntando isso ao endpoint e ao cabeçalho de autenticação do Freshdesk, você chega à configuração abaixo, que é minha própria montagem das duas documentações e não um exemplo oficial:

mcp_servers:
  freshdesk:
    url: "https://yourcompany.freshdesk.com/mcp"
    headers:
      Authorization: "${FRESHDESK_API_KEY}"
    tools:
      include:
        - fetchTicket
        - fetchTicketConversations
        - fetchSearchTickets
        - fetchSolutionArticle
        - createTicketNote

Depois que include é definido, a documentação do Hermes diz: "Only those MCP server tools are registered." Então essa lista curta acaba fazendo o trabalho que as permissões do Freshdesk não conseguem fazer.

O Hermes também tem uma configuração trust por servidor. Em um servidor untrusted, "every write-capable tool call... requires user approval through the standard approval surface before it runs" (referência de configuração MCP). O padrão é full. Caso você rode o Hermes a partir de um chat do Slack ou Telegram com uma pessoa acompanhando, mudar para untrusted dá uma segunda checagem em cada nota.

3. Escreva notas privadas, nunca respostas

O Freshdesk mantém as duas coisas separadas no nível da API. Uma nota que você adiciona por /notes é privada por padrão, e "Private notes are for collaboration between agents and are not visible to the customer." O endpoint de atualização, por outro lado, diz "Only public & private notes can be edited" (API do Freshdesk). Uma vez enviada, a resposta fica enviada.

Então o fluxo é assim: o Hermes redige em uma nota privada, um agente a lê e esse agente envia a resposta em seu próprio nome. As respostas rascunho com IA do Freshdesk funcionam no mesmo formato, e o mesmo vale para toda ferramenta de agent assist. Minha regra é manter assim até os erros ficarem chatos.

4. Escolha um gatilho: chat, cron ou webhook

O Hermes precisa saber quando olhar um ticket, e há três opções:

• Sob demanda. Um agente cola um número de ticket no Slack e pede um rascunho ao Hermes. É a mais simples, e uma pessoa continua no circuito o tempo todo.
• Consulta por cron. O agendador do Hermes bate a cada 60 segundos, e um script de pré-checagem pode imprimir {"wakeAgent": false} para que "cron skips the agent run entirely" quando nada mudou (documentação de cron). Bom para "a cada 5 minutos, redigir notas nos tickets novos deste grupo".
• Webhook. Uma regra de automação do Freshdesk na criação de ticket dispara "Trigger webhook" para uma rota do Hermes como http://your-server:8644/webhooks/freshdesk.

Das três, os webhooks são os mais próximos do tempo real e também os mais trabalhosos. O Hermes quer um segredo em cada rota e rejeita qualquer requisição sem "a recognized signature header" (documentação de webhooks). A regra do Freshdesk pode adicionar cabeçalhos personalizados, mas não encontrei opção de assinar o corpo, então antes de depender disso, teste qual dos esquemas aceitos pelo Hermes a sua regra realmente consegue satisfazer. Em caso de falha, o Freshdesk tenta de novo a cada 30 minutos, 48 vezes, e os webhooks são limitados a 1.000 chamadas por hora (ajuda do Freshdesk).

Alguns outros detalhes de webhook valem a pena. As execuções por webhook começam com um conjunto de ferramentas padrão bem restrito, o que significa que a rota precisa de uma concessão manual toolsets: ["mcp-freshdesk"] antes de poder tocar em qualquer ticket. A documentação também avisa: "HMAC validation authenticates the sender, not the content." Como um cliente escreve o corpo do ticket, trate-o como texto não confiável, e esse é mais um motivo para a única ferramenta de escrita ser uma nota privada.

5. Teste em tickets antigos antes de confiar

Aqui é onde eu investiria mais tempo, e também onde o Hermes menos ajuda. Ele não tem modo de reprodução para rodar sobre os tickets do mês passado e pontuar os rascunhos contra o que sua equipe realmente enviou.

Você pode montar isso por conta própria: puxar tickets resolvidos, rodar o Hermes sobre eles em um perfil isolado e depois comparar. Há duas armadilhas do Freshdesk. O List Tickets "by default" só retorna tickets "created within the past 30 days" a menos que você passe updated_since, e o endpoint de busca para em cerca de 300 resultados (API do Freshdesk). Além disso, cada leitura durante a avaliação conta contra a sua franquia MCP, então faz mais sentido rodar a avaliação pela API REST. Para saber como é "bom o bastante", meu guia sobre treinar IA em uma base de conhecimento explica.

Quanto o Hermes realmente custa no Freshdesk

A licença não custa nada. Os outros quatro itens da conta custam.

Ações MCP. "Any call to an MCP server counts as one action, regardless of whether it reads or writes data" (FAQs de MCP). A franquia é definida por conta e por ano, e não acumula:

O que passar disso custa US$ 15 por 1.000, conforme a página de preços. Os limites REST vêm da documentação da API e são compartilhados em toda a conta com qualquer outra integração que você rode.

Um rascunho útil leva mais de uma chamada. O Hermes lê o ticket, depois a conversa, busca tickets semelhantes e puxa um artigo de ajuda antes de escrever a nota:

Com cinco ações por ticket, o Growth cobre cerca de 240 rascunhos por ano, aproximadamente 20 por mês. Depois disso, sai a 7,5 centavos de dólar por ticket em ações, o que parece barato por ticket, mas é fácil de subestimar no total. Agentes também repetem e exploram, então trate cinco como o piso, não como a média. Você pode inserir seus próprios números aqui:

Tokens do modelo. O Nous Portal Plus custa US$ 20/mês por US$ 22 de crédito, o Super US$ 100 e o Ultra US$ 200. Outra opção é conectar um plano elegível do ChatGPT e usá-lo para a inferência.

A vaga do bot. De US$ 19 a US$ 89 por mês, dependendo do plano que você tem.

A construção. Este é o item que as pessoas costumam pular. Um comprador de Freshdesk nas ligações de vendas da eesel, uma empresa de segurança de e-mail a caminho de 20.000 tickets por ano, passou por 200 interações em um único dia de teste, e a primeira coisa que perguntou foi como isso ficaria com 9.000 por mês. Com IA medida por uso, o volume vira a primeira pergunta de um líder de suporte, e o Hermes faz você medir três coisas ao mesmo tempo: tokens e ações MCP, e ainda por cima horas de engenharia. Para esta última, meu detalhamento build vs buy traz números.

Onde o Hermes no Freshdesk deixa de funcionar

Tudo o que foi dito até aqui assume o formato de rascunhos. Quando você aponta o Hermes diretamente para clientes do Freshdesk, esbarra nas mesmas paredes que encontrei na análise de suporte geral:

• A memória é por perfil, não por solicitante. A memória integrada é MEMORY.md (2.200 caracteres) e USER.md (1.375), carregadas em toda sessão que o perfil executa (documentação de memória). O que ele salvar do ticket de um cliente fica então no prompt do próximo.
• Sem destino de entrega no Freshdesk. As opções deliver de uma execução por webhook são plataformas de chat, e-mail ou um log. Para levar a resposta de volta ao ticket, você sempre passa por uma chamada de ferramenta.
• Sem ensaio. Tratei disso acima, e é a lacuna à qual eu daria mais peso.
• O bot nativo já existe. O Freddy AI Agent do Freshdesk está em todos os planos com 500 sessões únicas, depois US$ 49 por 100. Se o que você quer é um bot voltado ao cliente dentro do Freshdesk, o Hermes estaria reconstruindo algo que o helpdesk já vende.

Há um usuário do Hacker News que de fato roda um helpdesk baseado no Hermes, e essa discussão resume bem o dilema:

"We replaced our helpdesk with Hermes. It has long term memory about our business. When a customer messages us, Hermes gets all the relevant details about the customer and creates a Pi session using Gemma 4 running locally and customer talks to that agent."

theturtletalks, Hacker News

A primeira resposta perguntou se isso arrisca "one customer's data leaking to another" (dezgeg, Hacker News). Olhe o desenho, porém. O Hermes não é o agente com quem o cliente fala; em vez disso, ele abre uma sessão local separada para cada cliente. É uma arquitetura sensata, e também muita arquitetura.

Hermes vs Freddy AI vs eesel no Freshdesk

Para a comparação mais ampla, meu levantamento best AI for Freshdesk e a lista Freshdesk AI alternatives vão mais fundo, enquanto Hermes Agent alternatives cobre o lado dos agentes gerais.

Você deveria rodar o Hermes na sua fila do Freshdesk?

Depois de ler as duas documentações, é aqui que chego.

Sim, se você tem um engenheiro que gosta desse tipo de trabalho e a tarefa é redigir notas para agentes que as revisam, desde que seu volume caiba na franquia de ações. O servidor MCP oficial com uma lista include de cinco ferramentas é uma configuração organizada que você consegue defender, e por cima dela os recursos de cron e webhook do Hermes dão automação de verdade. Ele também se encaixa bem como chatbot interno de suporte que responde à sua própria equipe a partir do histórico do Freshdesk.

Não, se você quer IA respondendo a clientes, ou precisa de um registro de cada ação da IA que um gerente de suporte consiga ler sem SSH. Mesma resposta se ninguém pode ser dispensado para manter um arquivo YAML e uma estrutura de avaliação. E a análise de segurança do Freshdesk que você faria em qualquer fornecedor passa a ser uma que você agora faz no seu próprio servidor.

A versão honesta é que o Freshdesk acabou de transformar a ligação na parte fácil. O que resta é o problema das alucinações de IA mais o ensaio e as proteções ao redor, e esse é o trabalho de verdade de colocar IA em uma fila.

eesel para Freshdesk

Se o motivo de você ter olhado o Hermes era querer que uma IA trabalhasse seus tickets do Freshdesk, a eesel é a colega construída exatamente para esse trabalho. Ela conecta com o subdomínio do seu Freshdesk e uma chave de API, sem app para instalar, e aprende com sua central de ajuda e respostas prontas, além dos tickets resolvidos (documentação da eesel).

Veja como ela cobre as lacunas acima:

• Ensaio primeiro. Ela simula nos seus tickets passados do Freshdesk antes de responder a um único cliente.
• Você escolhe o nível de escrita. Ela pode deixar notas internas, reter rascunhos de resposta para aprovação ou enviar. Aplicar tags e atribuir também estão incluídos, além de definir status e atualizar campos, o que cobre também a triagem automática do Freshdesk.
• Sem medição por chamada. Um ticket custa 1 crédito, não importa quantas respostas vão e voltam. Os planos começam em US$ 299 por 500 créditos, e o plano gratuito vem com 100 créditos.
• Freshchat incluído. A mesma conexão também cobre o chat do Freshdesk, então não há uma segunda configuração.

E se metade do atrativo do Hermes era o terminal, a eesel também tem um. A CLI da eesel controla a mesma colega: eesel integrations connect freshdesk conecta a conta, eesel integrations download start baixa o histórico de tickets e eesel automations define o que ela faz em cada gatilho. Como os comandos imprimem JSON, um script ou um agente de programação como o Claude Code pode executar sua configuração do Freshdesk do começo ao fim. Há mais sobre isso no meu post CLI for customer support.

Guarde o Hermes para os trabalhos em que ele é ótimo. Para a fila do Freshdesk, porém, experimente primeiro a eesel nos seus tickets reais.