Ligar um assistente de IA ao Helpdash com MCP

O Helpdash expõe um servidor Model Context Protocol (MCP), para que um assistente de IA possa trabalhar dentro do seu espaço de trabalho em vez de estar a copiar e colar pedidos numa janela de chat. Pergunte "que pedidos incumprem o SLA hoje?" ou "resume este fio para a passagem de turno" e o assistente consulta o próprio Helpdash.

Este artigo cobre o que o conector expõe, como ligar um e — a parte que merece duas leituras — o que não lhe é permitido fazer.

O que o conector expõe

O servidor traz 46 ferramentas, quatro instruções já prontas e um recurso que lista todos os valores de enumeração que as ferramentas aceitam. As ferramentas cobrem pedidos, chat ao vivo, base de conhecimento, respostas predefinidas, projetos e colegas, o painel, CSAT, regras de automatização, webhooks, definições, o registo de atividade e a faturação.

Leituras e escritas são sempre ferramentas separadas. Não existe uma ferramenta abrangente api_request com um parâmetro method — procurar pedidos e alterar um são ferramentas diferentes com permissões diferentes, por isso um assistente com acesso de leitura não pode alterar nada variando um argumento.

As quatro instruções são fluxos que vale a pena ter já escritos:

• Triar um pedido — recomenda prioridade, categoria e responsável. Não altera nada.
• Redigir uma resposta ao cliente — prepara o texto com a sua base de conhecimento e as respostas predefinidas. Não pode enviar; a resposta volta para si rever.
• Resumir um fio — condensa um pedido longo ou uma transcrição de chat para a passagem de turno.
• Relatório semanal de suporte — volume, SLA, CSAT e o que precisa de atenção.

Ligar um cliente

Abra Definições → Conectores de IA (MCP) e emita um token. Dê-lhe uma etiqueta que reconheça mais tarde, deixe todos os interruptores de escrita desligados no primeiro e copie a chave — é mostrada exatamente uma vez.

Depois registe-o. Para o Claude Code:

claude mcp add --transport http helpdash https://your-workspace.helpdash.io/mcp \
  --header "Authorization: Bearer hd_mcp_..."

Para qualquer cliente que leia um .mcp.json:

{
  "mcpServers": {
    "helpdash": {
      "type": "http",
      "url": "https://your-workspace.helpdash.io/mcp",
      "headers": { "Authorization": "Bearer hd_mcp_..." }
    }
  }
}

Ambos os excertos são gerados para si, já preenchidos com o endereço do seu espaço de trabalho, no mesmo ecrã onde o token aparece.

Os clientes que preferem iniciar sessão no navegador podem usar OAuth 2.1 em vez de um token estático: o servidor publica os documentos de descoberta padrão, suporta PKCE e o registo dinâmico de clientes, e mostra um ecrã de consentimento que enumera exatamente os âmbitos pedidos. Sem token para copiar e sem chave para guardar em disco.

O que não pode fazer

O conector não é uma segunda API mais permissiva. Cada chamada passa pelos mesmos quatro controlos que um pedido humano.

Age como si. Um token está ligado ao operador que o emitiu. Herda exatamente os seus papéis e permissões — se não consegue abrir um pedido na aplicação, um assistente com o seu token também não consegue. E está ligado a um espaço de trabalho: não há argumento que alcance os dados de outro inquilino.

Só leitura, a não ser que diga o contrário. Um token novo com todos os interruptores desligados pode procurar, ler e produzir relatórios, nada mais. O acesso de escrita é concedido por área — alterar pedidos, responder no chat ao vivo, editar a base de conhecimento, gerir projetos, convidar colegas, mudar definições, mudar regras de automatização — e apenas nas que marcar. A leitura está sempre incluída, porque um assistente que pode escrever mas não ler é inútil.

As ferramentas de escrita perguntam primeiro. Todas as ferramentas que alteram dados estão marcadas como destrutivas, por isso um cliente bem feito pergunta-lhe antes de cada chamada em vez de agir em silêncio. As ferramentas que chegam a um cliente dizem-no na sua própria descrição: uma mensagem de chat ao vivo é entregue de imediato e não pode ser retirada, e um comentário num pedido é, por omissão, uma nota interna, para que nada chegue ao cliente por acidente.

Os segredos ficam no servidor. Ler as suas definições através de um conector devolve as credenciais de integração mascaradas. Não há argumento que as revele.

O texto do cliente vai cercado. As descrições de pedidos, os comentários e as transcrições de chat são escritos por outras pessoas, e uma caixa de suporte é precisamente onde alguém tentaria plantar instruções para uma IA que as leia. O Helpdash envolve esse texto num bloco explícito de conteúdo não fiável e diz ao modelo, nas próprias instruções do servidor, que nada lá dentro é um comando.

Tudo fica registado. Cada chamada é registada com o operador, a ferramenta e o resultado, no mesmo registo de auditoria do resto do espaço de trabalho. Se algum dia precisar de responder a "o que é que o assistente fez mesmo na terça-feira?", o registo está lá.

A revogação é imediata. Apagar um token nas Definições trava logo o pedido seguinte do assistente. Guardamos apenas um hash SHA-256 da chave, por isso não a conseguimos recuperar por si — se a perder, emite uma nova.

Apertar ainda mais um token

Há dois controlos opcionais que vale a pena conhecer. Um token pode ter uma data de validade, a forma mais simples de uma experiência curta se limpar sozinha. E pode ter uma lista de IP permitidos, para que um token destinado a um servidor não possa ser usado a partir de outro sítio. Ambos estão no mesmo formulário de criação.

Um primeiro token sensato

Emita um sem âmbitos de escrita e dê ao assistente uma semana só de leitura. Peça-lhe para encontrar riscos de SLA, resumir fios longos e redigir respostas que envia você. Isso cobre quase todo o valor sem qualquer exposição. Quando souber que âmbito de escrita quer mesmo, emita um segundo token só com esse — alargar um token existente é deliberadamente impossível.

Todas as afirmações acima descrevem comportamento disponível hoje; o conector está disponível em qualquer espaço de trabalho Helpdash.