MCP: usar o Konversia por uma IA

O MCP (Model Context Protocol) é um jeito padronizado de entregar a uma inteligência artificial uma lista de ações que ela pode executar num sistema de verdade. Pense num cardápio: o Konversia publica o que pode ser feito (listar canais, consultar templates, enviar uma mensagem) e a IA escolhe o item certo quando você pede algo em português.

Na prática, conectar o servidor MCP do Konversia ao Claude significa que você passa a pedir as coisas por escrito, em linguagem comum, em vez de escrever código. "Quais canais estão conectados e quanta cota sobrou este mês?" vira uma chamada real à sua empresa, com a resposta na tela. É a mesma API pública descrita neste livro, só que operada por conversa.

Esta página é para quem vai conectar e usar. Se você prefere integrar pelo seu próprio sistema, veja Enviar mensagens; se prefere reagir a eventos do Konversia lá fora, veja Webhooks.

Como conectar no Claude

O endereço do servidor é o mesmo para todas as empresas: https://konversia.com.br/mcp. Quem identifica a sua empresa é a chave de API, não o endereço.

1. Crie uma chave de API no Konversia, em Configurações, aba API, com os escopos que o seu caso precisa. Veja Chaves de API.
2. No Claude, abra Configurações > Conectores > Adicionar conector personalizado.
3. Dê um nome ao conector (por exemplo, "Konversia") e informe a URL https://konversia.com.br/mcp.
4. Em Autenticação, escolha "Sem login", a opção descrita como para servidores que usam uma chave de API em vez de OAuth.
5. Em Cabeçalhos de requisição, adicione um cabeçalho com o nome Authorization e o valor Bearer <sua-chave>, exatamente como na Autenticação da API REST.
6. Salve.

"Configurações de login não encontradas" é esperado

Antes de você escolher a autenticação, o Claude procura sozinho por um login OAuth no endereço informado e avisa que não encontrou. Isso não é erro: o servidor do Konversia é autenticado por chave de API no cabeçalho, não por OAuth. Siga para o passo 4 normalmente.

Conectado, o conector passa a listar as ferramentas disponíveis, separadas entre as que só leem informação e as que pedem aprovação antes de rodar.

As nove ferramentas

Nome	Título na tela	O que faz	Escopo
whoami	Minha empresa	Mostra a empresa dona da chave, a situação da assinatura, os escopos liberados, o canal padrão e a cota de envio (usada, limite e restante)	nenhum
listar_canais	Listar canais	Lista as linhas de WhatsApp da empresa, com id, nome, provedor, status da conexão, setor padrão e o que cada uma suporta	channels:read
listar_templates	Listar templates	Lista os templates aprovados, com id, nome, idioma, categoria, corpo e quantas variáveis cada um espera	templates:read
status_da_mensagem	Status da mensagem	Consulta o que aconteceu com um envio feito pela API, a partir do identificador devolvido no aceite	messages:read
listar_arquivos	Listar arquivos	Lista os arquivos já no repositório da empresa (id, nome, tipo e tamanho), paginado, para reaproveitar um id	files:read
subir_arquivo	Subir arquivo	Sobe um arquivo novo para o repositório e devolve o id dele, que é o file_id usado no envio de mídia	files:write
enviar_texto	Enviar texto	Envia uma mensagem de texto para um número, com template de reserva opcional para a janela fechada	messages:send
enviar_midia	Enviar mídia	Envia um arquivo do repositório (imagem, vídeo, áudio ou documento), com legenda opcional	messages:send
enviar_template	Enviar template	Envia um template aprovado, dentro ou fora da janela de 24 horas	messages:send

As ferramentas espelham os endpoints da API REST, com as mesmas regras: a resolução do destino, a janela de 24 horas e o formato dos campos são os mesmos descritos em Enviar mensagens. Duas diferenças valem nota:

• enviar_midia só aceita um arquivo que já esteja no repositório, pelo file_id. Não existe envio por URL, pelo mesmo motivo explicado no envio em duas etapas da API REST.
• status_da_mensagem usa o identificador devolvido no envio, não o número interno da mensagem no banco.

Exemplos de pedido

Escrito assim, em português comum, na conversa com a IA:

• "No Konversia, quais canais estão conectados e quanta cota de envio ainda tenho este mês?"
• "Lista os templates aprovados da minha empresa e me diz quantas variáveis cada um espera."
• "Manda uma mensagem para o 5511999998888 avisando que o pedido saiu para entrega hoje."
• "Envia o template aviso_boleto em pt_BR para o 5511999998888, com a variável 8842."
• "Aquela mensagem que você mandou agora já foi entregue?"
• "Sobe este PDF para o repositório e manda para o 5511999998888 com a legenda 'Segue o boleto de agosto'."

Segurança

O MCP não tem poder próprio. Ele passa pela mesma pilha da API REST: a mesma autenticação por chave, a mesma checagem de assinatura ativa, o mesmo controle de limite de chamadas e a mesma medição de uso. Nada que a API REST não exponha fica exposto aqui.

• Os escopos valem igual. Cada ferramenta exige o escopo da tabela acima e checa antes de fazer qualquer coisa. Uma chave sem messages:send não envia mensagem, ponto final, por mais que o pedido esteja bem escrito. A recusa vem com o código forbidden_scope, o mesmo da API REST.
• As quatro ferramentas de escrita pedem aprovação. subir_arquivo, enviar_texto, enviar_midia e enviar_template são declaradas como ações que mudam o mundo, então o cliente MCP pergunta antes de disparar. Você confirma cada envio.
• Dado de outra empresa não existe para a sua chave. Um id de mensagem, arquivo ou canal de outra empresa devolve o mesmo erro genérico de "não encontrado", sem confirmar que aquele id existe em algum lugar.
• A cota é a mesma. Um envio pelo MCP consome a cota mensal da empresa exatamente como um envio pela tela, por campanha ou pela API. Use whoami para ver quanto sobra.

Uma chave de leitura e outra de envio

Quem tem o conector configurado age com aquela chave. Vale criar duas: uma só com os escopos de leitura (channels:read, templates:read, messages:read, files:read) para explorar e conferir informação sem risco, e outra separada, com messages:send e files:write, para quando for de fato disparar mensagem. Revogar uma delas em Configurações, aba API, desliga só aquele uso.

Limites e comportamentos

Limite de chamadas

60 requisições por minuto por chave de API, contadas num balde próprio, separado do limite da API REST. Um agente conversando não compete com o tráfego do seu sistema, e vice-versa.

Toda mensagem do protocolo conta, não só as chamadas de ferramenta: o aperto de mão inicial (a conexão) e a listagem das ferramentas (tools/list) também entram nas 60 por minuto.

Tamanho do arquivo em subir_arquivo

4 MB por arquivo, menor que o limite de 15 MB do POST /v1/files. O motivo é o transporte: no MCP o conteúdo viaja codificado dentro da própria chamada, não como um anexo à parte, e cresce cerca de um terço no caminho. Arquivo maior continua subindo pela API REST ou pela tela; depois é só usar listar_arquivos para pegar o id.

O tipo é identificado pelo conteúdo real do arquivo, nunca pela extensão do nome. São aceitos imagem (jpg, png, gif, webp), vídeo (mp4, webm, 3gp), áudio (mp3, aac, ogg, wav), PDF, Word (doc, docx), Excel (xls, xlsx), CSV, texto simples e zip. HTML, SVG e qualquer executável são recusados.

Envio repetido

Não existe cabeçalho de idempotência aqui: um envio pelo MCP se comporta como uma chamada REST feita sem Idempotency-Key.

O que continua valendo é o guarda de mensagem duplicada: se a mesma mensagem, com o mesmo conteúdo, for pedida de novo para a mesma conversa dentro de uma janela de 90 segundos, a segunda não sai. E ela não sai em silêncio do ponto de vista de quem pediu: a IA recebe o aceite normal, mas a mensagem fica com o status skipped, visível em status_da_mensagem.

Na prática: se você pedir duas vezes "avisa o cliente que o pedido saiu para entrega" em seguida, o cliente recebe uma mensagem só. Para as duas saírem, mude alguma coisa no texto, por exemplo o número do pedido.

Erros

Quando uma ferramenta recusa, a mensagem de erro carrega o mesmo código estável da API REST (outside_24h_window, template_not_approved, quota_exceeded, file_not_found e os demais de Erros), junto com os detalhes que ensinam a correção, como a lista de templates aprovados naquele canal ou quantas variáveis o template espera. Isso é o que costuma permitir que a IA corrija o pedido sozinha e tente de novo, em vez de só avisar que falhou.

Relacionado

• Autenticação
• Enviar mensagens
• Erros
• Chaves de API (guia do produto)