![Visão geral da integração MCP: gerar o token de acesso no perfil, conectar o assistente ao endereço /mcp da sua instância, consultar conversas e contatos com as suas permissões e receber respostas como rascunho para revisão humana.](/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBbzhTIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--6abd5db75a7c9048815c32e866467372cff455f5/conectar-assistentes-de-ia-com-mcp.png)

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](mailto:atendimento@chatwoot.app.br) 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:

| Grupo | O que faz |
| --- | --- |
| **Consultas** | Buscar e ler conversas, buscar e ler contatos, ver um resumo da conta e pesquisar na Central de Ajuda |
| **Rascunho de resposta** | Salvar uma sugestão de resposta como **nota privada**, para uma pessoa revisar e enviar |
| **Alterações diretas** | Adicionar nota, atribuir conversa, alterar etiquetas, mudar status, atualizar contato e mover etapa do funil |

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`:

```text
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:

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

No **VS Code**, adicione ao seu `mcp.json`:

```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](https://nodejs.org/) instalado.

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

```json
{
  "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

| O que você vê | O que costuma ser |
| --- | --- |
| Erro **404** ou o endereço simplesmente não responde | O recurso ainda não foi ativado na sua conta, ou a instância está numa versão anterior à que inclui o MCP. Fale com o suporte. |
| Erro **401** | Token incorreto, revogado, ou o usuário do token não tem acesso à conta informada no endereço. |
| Mensagem citando **400** e listando endereços | Seu usuário participa de mais de uma conta. Use o endereço com o número da conta, como indicado na própria mensagem. |
| Erro **429** | Limite de requisições por minuto atingido. Aguarde um instante e tente de novo. |
| No Claude Desktop: erro citando **OAuth**, **404** e `Unexpected token '<'` | Apesar do texto, isso é **token inválido**. Gere um novo token e atualize o arquivo de configuração. |
| No Claude Desktop: o servidor sumiu — e os outros também | O campo `url` foi usado no arquivo de configuração. Reescreva no formato `command`/`args` mostrado acima. |

## 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](1730736611-como-usar-apps-no-dashboard)
- [Como usar webhooks?](1730735980-como-usar-webhooks)