Servidor MCP: ferramentas MCP e configuração no Claude, Cursor, VS Code e Windsurf # Servidor MCP > Servidor MCP da TopTalking (Streamable HTTP em https://platform.toptalking.com.br/mcp) - conecte Claude, Cursor, VS Code e Windsurf à sua conta com a chave de API e veja todas as ferramentas disponíveis. 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](/comecando/autenticacao/) | ## Conectar o seu cliente [Claude Code](/mcp/claude-code/)Um comando no terminal. [Claude Desktop](/mcp/claude-desktop/)Via mcp-remote no claude_desktop_config.json. [Cursor](/mcp/cursor/)\~/.cursor/mcp.json com URL e cabeçalho. [VS Code e Windsurf](/mcp/vscode-windsurf/)Copilot (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](/referencia/visao-geral/): 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`](/referencia/canais/#criar-canal)) ou ter um novo QR Code gerado com [`POST /channels/{channel_id}/connect`](/referencia/canais/#gerar-qr-code-ou-c%C3%B3digo-de-pareamento). Veja o fluxo completo em [Conectar um WhatsApp por QR Code](/referencia/canais/#conectar-um-whatsapp-por-qr-code). ## Segurança A IA age na sua conta de verdade As ferramentas mandam mensagens **reais** para os seus clientes pelo WhatsApp da empresa. Um pedido mal interpretado pode virar uma mensagem errada para a pessoa errada. * **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](/comecando/boas-praticas-whatsapp/): nada de disparos em massa pela IA. ## Exemplos de pedidos ```text Quais conversas receberam mensagem hoje e ainda estão sem resposta? ``` ```text Mostre o funil do Kanban: quantos contatos há em cada etapa? ``` ```text Leia as últimas 20 mensagens da conversa com a Maria Souza e resuma o que ela quer. ``` ```text Mova o João Pereira para a etapa "Negociação", desligue a IA nessa conversa e atribua à Carla. ``` ```text Mostre o QR Code do canal "Pós-venda" para eu conectar o WhatsApp e me avise quando conectar. ``` ```text Quais campanhas estão em andamento e quantas mensagens já foram entregues em cada uma? ``` ```text Quem escreveu no grupo "Equipe de Vendas" hoje? Resuma as últimas 30 mensagens. ``` ```text 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](/mcp/claude-desktop/). No claude.ai, use um Projeto com a documentação (veja [Claude](/ia/claude/#claudeai-projetos)). * **ChatGPT — conectores:** também exigem OAuth. Use um **GPT personalizado com Actions** importando o OpenAPI: veja [ChatGPT](/ia/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`](/referencia/canais/#reconectar-um-whatsapp-desconectado) 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](/mcp/claude-desktop/)). | # MCP no Claude Code > Conecte o Claude Code ao servidor MCP da TopTalking com um comando (claude mcp add --transport http), escolha o escopo e configure permissões para as ferramentas que enviam mensagens. O **Claude Code** (a ferramenta de linha de comando da Anthropic) suporta servidores MCP por HTTP nativamente. ## Instalar 1. Gere uma chave em [Configurações → Desenvolvedor](https://toptalking.com.br/configuracoes/desenvolvedor). Para começar, prefira **Somente leitura**. 2. No terminal, rode (troque `tt_live_SUA_CHAVE` pela sua chave): ```bash claude mcp add --transport http toptalking https://platform.toptalking.com.br/mcp --header "Authorization: Bearer tt_live_SUA_CHAVE" ``` 3. Confira se conectou: ```bash claude mcp list ``` Dentro do Claude Code, o comando `/mcp` mostra o status e as ferramentas da `toptalking`. 4. Peça algo como: “Use a TopTalking para listar as etapas do Kanban e quantos contatos há em cada uma.” ## Escopos Por padrão o servidor fica disponível só para você, no projeto atual (`--scope local`). Outras opções: | Escopo | Comando | Onde fica | | -------------------------- | ------------------------ | ------------------------------------------ | | Só você, este projeto | `--scope local` (padrão) | Configuração local do Claude Code | | Só você, todos os projetos | `--scope user` | Configuração do seu usuário | | Todo o time, este projeto | `--scope project` | Arquivo `.mcp.json` na raiz do repositório | ```bash # Disponível em todos os seus projetos claude mcp add --transport http --scope user toptalking https://platform.toptalking.com.br/mcp --header "Authorization: Bearer tt_live_SUA_CHAVE" ``` ### Compartilhar com o time sem expor a chave O `.mcp.json` vai para o Git. **Não coloque a chave nele**: use uma variável de ambiente, que o Claude Code expande ao carregar o arquivo. .mcp.json ```json { "mcpServers": { "toptalking": { "type": "http", "url": "https://platform.toptalking.com.br/mcp", "headers": { "Authorization": "Bearer ${TOPTALKING_API_KEY}" } } } } ``` Cada pessoa define `TOPTALKING_API_KEY` na própria máquina (de preferência com a própria chave). ## Permissões O Claude Code pede confirmação antes de usar uma ferramenta MCP. Você pode liberar de vez **só as ferramentas de leitura** e continuar aprovando manualmente as que enviam mensagens: .claude/settings.json ```json { "permissions": { "allow": [ "mcp__toptalking__get_account", "mcp__toptalking__list_channels", "mcp__toptalking__search_contacts", "mcp__toptalking__get_contact", "mcp__toptalking__list_messages", "mcp__toptalking__list_stages", "mcp__toptalking__list_scheduled_messages", "mcp__toptalking__list_groups", "mcp__toptalking__list_members", "mcp__toptalking__list_ai_agents", "mcp__toptalking__list_templates", "mcp__toptalking__list_campaigns", "mcp__toptalking__get_channel_qr" ] } } ``` Cuidado Não libere automaticamente `send_message`, `schedule_message`, `update_contact`, `upsert_contact` nem `cancel_scheduled_message`. Elas agem na conta real. ## Remover ```bash claude mcp remove toptalking ``` ## Próximos passos * Quer que o Claude Code **escreva uma integração** com a API (e não só use o MCP)? Veja o guia [Claude](/ia/claude/#claude-code), com um `CLAUDE.md` pronto. * Todas as ferramentas e cuidados: [Servidor MCP](/mcp/visao-geral/). # MCP no Claude Desktop > Conecte o app Claude Desktop (Windows e macOS) ao servidor MCP da TopTalking usando o mcp-remote no claude_desktop_config.json, com o cabeçalho de autorização numa variável de ambiente. Os “conectores personalizados” do Claude Desktop exigem login por OAuth, que a TopTalking ainda não suporta. A forma de conectar é pelo arquivo de configuração, usando o [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) — uma ponte que roda na sua máquina e fala com o servidor da TopTalking por HTTP. **Requisito:** [Node.js](https://nodejs.org) 18 ou mais novo instalado (o comando `npx` precisa funcionar no terminal). ## Configurar 1. Gere uma chave em [Configurações → Desenvolvedor](https://toptalking.com.br/configuracoes/desenvolvedor). Para começar, prefira **Somente leitura**. 2. No Claude Desktop, abra **Configurações → Desenvolvedor → Editar configuração**. Isso abre o arquivo `claude_desktop_config.json`: * Windows ```text %APPDATA%\Claude\claude_desktop_config.json ``` * macOS ```text ~/Library/Application Support/Claude/claude_desktop_config.json ``` 3. Cole a configuração abaixo (se o arquivo já tiver outros servidores, adicione só o bloco `toptalking` dentro de `mcpServers`) e troque `tt_live_SUA_CHAVE` pela sua chave: claude_desktop_config.json ```json { "mcpServers": { "toptalking": { "command": "npx", "args": [ "-y", "mcp-remote", "https://platform.toptalking.com.br/mcp", "--header", "Authorization:${TOPTALKING_AUTH}" ], "env": { "TOPTALKING_AUTH": "Bearer tt_live_SUA_CHAVE" } } } } ``` 4. **Feche o Claude Desktop por completo** (inclusive o ícone perto do relógio, no Windows) e abra de novo. 5. Num chat novo, clique no ícone de ferramentas: a `toptalking` deve aparecer com as ferramentas listadas. ## Por que o cabeçalho está numa variável? Repare que o argumento é `Authorization:${TOPTALKING_AUTH}` — **sem espaço** depois dos dois-pontos — e o valor `Bearer tt_live_...` fica em `env`. No Windows, argumentos com espaço (como `Authorization: Bearer tt_live_...`) costumam ser quebrados no caminho até o `npx`, e o cabeçalho chega errado. O `mcp-remote` substitui `${TOPTALKING_AUTH}` pelo valor da variável, então o espaço nunca passa pela linha de comando. Funciona igual no macOS. ## Problemas comuns | Sintoma | O que fazer | | -------------------------- | ------------------------------------------------------------------------------------------------------- | | A `toptalking` não aparece | Confira se o JSON é válido (vírgulas!) e se você fechou o app por completo antes de abrir de novo. | | Erro com `npx` | Instale o Node.js 18+ e teste `npx --version` no terminal. | | Erro 401 | Confira o valor de `TOPTALKING_AUTH`: precisa começar com `Bearer `(com espaço) seguido da chave. | | Ver os logs | No Windows: `%APPDATA%\Claude\logs`. No macOS: `~/Library/Logs/Claude`. Procure os arquivos `mcp*.log`. | Veja as ferramentas e os cuidados de segurança em [Servidor MCP](/mcp/visao-geral/). # MCP no Cursor > Conecte o Cursor ao servidor MCP da TopTalking pelo arquivo ~/.cursor/mcp.json (URL + cabeçalho Authorization) e use as ferramentas no modo Agent. O Cursor conecta direto em servidores MCP por HTTP, com cabeçalhos personalizados. ## Configurar 1. Gere uma chave em [Configurações → Desenvolvedor](https://toptalking.com.br/configuracoes/desenvolvedor). Para começar, prefira **Somente leitura**. 2. Abra (ou crie) o arquivo **`~/.cursor/mcp.json`** — a configuração global, fora de qualquer repositório. No Windows, fica em `%USERPROFILE%\.cursor\mcp.json`. 3. Cole e troque `tt_live_SUA_CHAVE` pela sua chave: \~/.cursor/mcp.json ```json { "mcpServers": { "toptalking": { "url": "https://platform.toptalking.com.br/mcp", "headers": { "Authorization": "Bearer tt_live_SUA_CHAVE" } } } } ``` 4. Abra as configurações do Cursor, na seção de **MCP**, e confirme que a `toptalking` aparece ativa, com as ferramentas listadas. 5. No chat, em modo **Agent**, peça: “Use a TopTalking para listar meus canais de WhatsApp e dizer se estão conectados.” Configuração por projeto O Cursor também lê `.cursor/mcp.json` dentro do projeto. Se usar esse arquivo, **não faça commit dele com a chave** — adicione-o ao `.gitignore`. Para o seu uso pessoal, prefira o arquivo global. ## Dicas * O Cursor pede confirmação antes de rodar ferramentas. Mantenha a confirmação para `send_message`, `schedule_message` e `update_contact`. * Para o Cursor **escrever código** que integra com a API (além de usar o MCP), adicione a documentação como `@Docs` e use as regras prontas do guia [Cursor, Windsurf e Copilot](/ia/cursor/). Veja as ferramentas e os cuidados de segurança em [Servidor MCP](/mcp/visao-geral/). # MCP no VS Code e no Windsurf > Conecte o VS Code (GitHub Copilot no modo agente, com .vscode/mcp.json e chave pedida com segurança) e o Windsurf (mcp_config.json com serverUrl) ao servidor MCP da TopTalking. * VS Code (Copilot) O VS Code usa servidores MCP no **GitHub Copilot Chat, em modo agente**. Com um `inputs` do tipo senha, o VS Code **pergunta a chave na primeira vez e guarda com segurança** — o arquivo pode ir para o Git sem expor nada. 1. Gere uma chave em [Configurações → Desenvolvedor](https://toptalking.com.br/configuracoes/desenvolvedor). 2. Crie o arquivo `.vscode/mcp.json` no projeto: .vscode/mcp.json ```json { "inputs": [ { "id": "toptalking-key", "type": "promptString", "password": true, "description": "Chave de API da TopTalking" } ], "servers": { "toptalking": { "type": "http", "url": "https://platform.toptalking.com.br/mcp", "headers": { "Authorization": "Bearer ${input:toptalking-key}" } } } } ``` 3. Clique em **Start** sobre o servidor no próprio arquivo (ou rode o comando **MCP: List Servers**) e cole a chave quando o VS Code pedir. 4. Abra o Copilot Chat, escolha o modo **Agent** e confira no seletor de ferramentas se as da `toptalking` estão marcadas. 5. Peça: “Liste as etapas do Kanban da TopTalking e quantos contatos há em cada uma.” * Windsurf O Windsurf (Cascade) lê os servidores MCP de um arquivo global. 1. Gere uma chave em [Configurações → Desenvolvedor](https://toptalking.com.br/configuracoes/desenvolvedor). 2. Abra o arquivo `~/.codeium/windsurf/mcp_config.json` (no Windows, `%USERPROFILE%\.codeium\windsurf\mcp_config.json`) — também dá para abrir pelo painel de MCP do Cascade. 3. Cole e troque `tt_live_SUA_CHAVE` pela sua chave: \~/.codeium/windsurf/mcp_config.json ```json { "mcpServers": { "toptalking": { "serverUrl": "https://platform.toptalking.com.br/mcp", "headers": { "Authorization": "Bearer tt_live_SUA_CHAVE" } } } } ``` 4. No Cascade, atualize a lista de servidores MCP e confirme que a `toptalking` aparece com as ferramentas. 5. Peça: “Use a TopTalking para buscar o contato com telefone 5511999998888.” Veja as ferramentas e os cuidados de segurança em [Servidor MCP](/mcp/visao-geral/). Para a IA escrever código de integração, use as regras prontas em [Cursor, Windsurf e Copilot](/ia/cursor/).