Servidor MCP

O MCP (Model Context Protocol) é o padrão que ferramentas de IA usam para acessar sistemas externos. Com o servidor MCP da TopTalking, você pede em português para o Claude, o Cursor ou o Copilot — “quem me mandou mensagem hoje?”, “mova a Maria para Negociação”, “agende um lembrete para amanhã às 9h” — e a IA usa a sua conta para fazer.


Endereço	`https://platform.toptalking.com.br/mcp`
Transporte	Streamable HTTP (sem estado; respostas em JSON)
Autenticação	Cabeçalho `Authorization: Bearer tt_live_...` — a mesma chave de API

Conectar o seu cliente

Claude CodeUm comando no terminal.

Claude DesktopVia mcp-remote no claude_desktop_config.json.

Cursor~/.cursor/mcp.json com URL e cabeçalho.

VS Code e WindsurfCopilot (modo agente) e Windsurf Cascade.

Ferramentas

São 18 ferramentas: 13 de leitura e 5 que alteram a conta.

Ferramenta	Tipo	O que faz	Parâmetros
`get_account`	leitura	Organização e chave em uso.	—
`list_channels`	leitura	Canais (WhatsApp e Chat do site) e se estão conectados.	—
`get_channel_qr`	leitura	QR Code atual de um canal de WhatsApp como imagem (o assistente mostra na conversa) e o status da conexão.	`channel_id`
`search_contacts`	leitura	Busca contatos por nome, telefone ou etapa.	`query?`, `phone?`, `stage_id?`, `limit?`
`get_contact`	leitura	Detalhes de um contato.	`contact_id`
`list_messages`	leitura	Histórico da conversa de um contato (ou grupo).	`contact_id`, `limit?`
`list_groups`	leitura	Grupos do WhatsApp (o `id` do grupo é o `contact_id` da conversa).	`query?`, `limit?`, `cursor?`
`list_stages`	leitura	Etapas do Kanban, em ordem.	—
`list_scheduled_messages`	leitura	Mensagens agendadas.	`status?`, `contact_id?`, `limit?`
`list_members`	leitura	Membros da equipe (para atribuir conversas).	—
`list_ai_agents`	leitura	Agentes de IA e qual é o padrão.	—
`list_templates`	leitura	Templates do WhatsApp Oficial para campanhas.	`ready?`
`list_campaigns`	leitura	Campanhas, com status, contadores e preço.	`status?`, `limit?`, `cursor?`
`upsert_contact`	escrita	Cria ou atualiza um contato pelo telefone.	`phone`, `name?`, `email?`, `stage_id?`
`update_contact`	escrita	Atualiza um contato: nome, e-mail, etapa do Kanban, responsável, fixar, agente de IA, IA ligada, finalizar, arquivar.	`contact_id`, `name?`, `email?`, `stage_id?`, `assigned_to?`, `pinned?`, `ai_agent_id?`, `ai_enabled?`, `resolved?`, `archived?`
`send_message`	envia mensagem	Envia texto e/ou mídia pelo WhatsApp.	`to?` ou `contact_id?`, `text?`, `media_url?`, `media_type?`, `filename?`, `channel_id?`
`schedule_message`	envia mensagem	Agenda uma mensagem (aparece na Agenda).	`to?` ou `contact_id?`, `send_at`, `text`, `title?`
`cancel_scheduled_message`	escrita	Cancela uma mensagem agendada pendente.	`scheduled_message_id`

(? = opcional.) As ferramentas seguem as mesmas regras da API REST: mesmos limites, mesmos erros e tudo aparece no painel.

Com uma chave Somente leitura, o servidor só expõe as 13 ferramentas de leitura — a IA nem enxerga as de escrita.

Conectar um WhatsApp pelo assistente

get_channel_qr devolve duas partes: uma imagem PNG do QR Code (o Claude e outros clientes compatíveis mostram direto na conversa) e um texto com status, channel, qr_code_generated_at e instrucoes (o que fazer no celular). Peça de novo a cada ~20–30 segundos até o status virar connected — o QR Code é renovado nesse intervalo.

A ferramenta lê o pareamento em andamento (canal connecting): o canal precisa ter sido criado (no painel ou com POST /channels) ou ter um novo QR Code gerado com POST /channels/{channel_id}/connect. Veja o fluxo completo em Conectar um WhatsApp por QR Code.

Segurança

Comece com uma chave Somente leitura para explorar, montar relatórios e testar prompts.
Revise cada chamada de send_message, schedule_message e update_contact antes de aprovar. Não ative “aprovar tudo automaticamente” para essas ferramentas.
Crie uma chave só para a IA, com nome claro (ex.: “Claude do time de vendas”) e validade, e revogue quando não usar mais.
Não cole a chave em chats nem em arquivos que vão para o Git. Prefira variáveis de ambiente quando o cliente suportar.
Lembre-se das boas práticas no WhatsApp: nada de disparos em massa pela IA.

Exemplos de pedidos

Quais conversas receberam mensagem hoje e ainda estão sem resposta?

Mostre o funil do Kanban: quantos contatos há em cada etapa?

Leia as últimas 20 mensagens da conversa com a Maria Souza e resuma o que ela quer.

Mova o João Pereira para a etapa "Negociação", desligue a IA nessa conversa e atribua à Carla.

Mostre o QR Code do canal "Pós-venda" para eu conectar o WhatsApp e me avise quando conectar.

Quais campanhas estão em andamento e quantas mensagens já foram entregues em cada uma?

Quem escreveu no grupo "Equipe de Vendas" hoje? Resuma as últimas 30 mensagens.

Agende para amanhã às 9h (horário de Brasília) uma mensagem para 5511999998888:
"Oi {{nome}}, passando para lembrar da sua consulta às 10h." Mostre antes de agendar.

E o claude.ai e o ChatGPT?

claude.ai (web) e Claude Desktop — “conectores personalizados”: exigem login por OAuth, que o servidor da TopTalking ainda não suporta. No Claude Desktop, use a configuração com mcp-remote. No claude.ai, use um Projeto com a documentação (veja Claude).
ChatGPT — conectores: também exigem OAuth. Use um GPT personalizado com Actions importando o OpenAPI: veja ChatGPT.

Problemas comuns

Sintoma	O que fazer
Erro 401 / “unauthorized”	Confira o cabeçalho: `Authorization: Bearer tt_live_...` (com `Bearer` e um espaço). A chave pode ter sido revogada ou expirado.
A IA não vê as ferramentas de envio	A chave é Somente leitura. Crie uma com Acesso total se quiser permitir escrita.
“channel_unavailable” ao enviar	O WhatsApp está desconectado. Reconecte no painel em Configurações → Conexões ou gere um novo QR Code com `POST /channels/{channel_id}/connect` e peça à IA para mostrá-lo com `get_channel_qr`.
`get_channel_qr` não mostra QR Code	Não há pareamento em andamento (o canal está `disconnected` ou já `connected`). Gere um novo QR Code no painel ou com `POST /channels/{channel_id}/connect`.
O cliente não conecta	Confirme que ele suporta MCP por HTTP (Streamable HTTP). Clientes que só aceitam `stdio` precisam do `mcp-remote` (veja Claude Desktop).