Conectar assistentes de IA ao Chatwoot com MCP

Sua equipe já usa um assistente de IA no dia a dia — para escrever, resumir, investigar. O MCP (Model Context Protocol) permite que esse assistente converse com o seu Chatwoot: em vez de você copiar e colar o histórico de um atendimento no chat da IA, o assistente consulta a conversa diretamente na sua conta.

Na prática, você passa a poder pedir coisas como:

• "Resuma as últimas conversas do cliente Fulano."
• "Quantas conversas estão abertas hoje e em quais caixas de entrada?"
• "Procure na Central de Ajuda como configurar um canal de WhatsApp e prepare uma resposta."

Disponibilidade: o MCP faz parte do plano Empresarial. O recurso não vem ligado por padrão — fale com o nosso time para ativá-lo na sua conta antes de seguir os passos abaixo.

O que o assistente pode fazer

O assistente enxerga a sua conta com as suas permissões — nem mais, nem menos. Se você é agente e não vê determinada conversa no painel, o assistente também não vê.

As ações disponíveis se dividem em três grupos:

Duas observações importantes sobre esses grupos:

• O assistente nunca envia mensagem para o cliente. Quando você pede uma resposta, ela é salva como nota privada na conversa, identificada como rascunho. Uma pessoa revisa, ajusta e envia — o envio continua sendo sempre humano.
• As alterações diretas valem na hora. Mudar o status ou atribuir uma conversa tem o mesmo efeito que fazer isso pelo painel, inclusive disparando automações que você tenha configurado. Trate esses pedidos como ações reais.

Passo 1 — Gerar seu token de acesso

A conexão é autenticada com o token do seu usuário. Para gerá-lo:

1. Clique no seu avatar, no canto inferior esquerdo do painel, e abra Configurações do perfil.
2. Role até a seção Token de acesso.
3. Copie o token exibido.

Esse token vale como a sua senha: quem o tiver consegue agir na conta como você. Não o compartilhe e não o publique em repositórios. Se suspeitar que vazou, volte nessa mesma tela e gere um novo — o anterior deixa de funcionar imediatamente.

Passo 2 — Conectar o seu assistente

O endereço do servidor MCP é o endereço do seu Chatwoot seguido de /mcp:

https://SEU-DOMINIO/mcp

Se o seu usuário participa de mais de uma conta, informe o número da conta no final — https://SEU-DOMINIO/mcp/1. O número da conta aparece na URL do painel quando você está logado (/app/accounts/1/...). Na dúvida, use a forma com número: ela evita ambiguidade quando uma segunda conta for habilitada.

Claude Code e VS Code

Esses dois já falam MCP por HTTP nativamente. No Claude Code, um comando basta:

claude mcp add --transport http chatwoot https://SEU-DOMINIO/mcp \
  --header "Authorization: Bearer SEU-TOKEN"

No VS Code, adicione ao seu mcp.json:

{
  "servers": {
    "chatwoot": {
      "type": "http",
      "url": "https://SEU-DOMINIO/mcp",
      "headers": { "Authorization": "Bearer SEU-TOKEN" }
    }
  }
}

Claude Desktop

O Claude Desktop não conecta direto a um servidor MCP pelo arquivo de configuração — ele só sabe iniciar programas locais. Por isso a conexão passa por uma ponte, o mcp-remote, que o próprio Claude Desktop executa. É necessário ter o Node.js instalado.

Abra Configurações → Desenvolvedor → Editar configuração e use este conteúdo:

{
  "mcpServers": {
    "chatwoot": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://SEU-DOMINIO/mcp/1",
        "--transport", "http-only",
        "--header", "Authorization:${AUTH_HEADER}"
      ],
      "env": { "AUTH_HEADER": "Bearer SEU-TOKEN" }
    }
  }
}

Depois feche o Claude Desktop por completo e abra de novo — ele só lê esse arquivo ao iniciar.

Dois cuidados nesse arquivo:

• Não use o campo url. Ele existe em outros programas, mas aqui não funciona: ao encontrá-lo, o Claude Desktop apaga silenciosamente toda a seção mcpServers, derrubando junto os outros servidores que você tenha configurado.
• O token fica gravado em texto puro nesse arquivo, no seu computador. Prefira gerar o token a partir de um usuário com as permissões mínimas necessárias e revogue-o se o equipamento for compartilhado ou perdido.

Passo 3 — Conferir se funcionou

Abra o seu assistente e peça algo simples de verificar, como um resumo da conta. Os números devem bater com o que você vê no painel.

Se listar as ferramentas disponíveis, você deve encontrar 13 ferramentas com o prefixo chatwoot_. Uma lista menor costuma indicar que a sua instância ainda não está na versão que inclui o recurso — nesse caso, fale com o suporte.

Se algo não funcionar

Boas práticas

• Um token por pessoa. Como o assistente herda as permissões do usuário do token, evite usar um token de administrador para tarefas que não precisam desse alcance.
• Revise antes de enviar. O rascunho de resposta existe justamente para manter a pessoa no controle da mensagem que chega ao cliente.
• Atenção ao conteúdo do cliente. Mensagens e dados de contato são escritos por terceiros. O servidor já marca esse conteúdo como dado — e não como instrução — para o assistente, mas vale manter o olhar crítico sobre respostas geradas a partir deles.
• Revogue o que não usa. Trocou de computador ou parou de usar a integração? Gere um novo token na tela de perfil para invalidar o anterior.

Artigos relacionados

• Como usar apps no dashboard
• Como usar webhooks?