Assistentes de IA (MCP)

O DevZap tem um servidor MCP (Model Context Protocol) em /api/v1/mcp. Um assistente de IA que fala MCP, como o Claude Code, o claude.ai, o Cursor e o Codex, consulta a conta em português: quais números estão conectados, quem tem cada etiqueta, o que saiu para um cliente ontem. Quando o plano inclui o envio pelo assistente, ele também manda mensagem, põe na fila e põe ou tira etiqueta.

Cada ferramenta chama a mesma rota da API que o seu sistema usaria, com a mesma chave. Os escopos, o plano, o dono da instância e os limites valem igual.

Há dois jeitos de conectar:

• Pelo login (Claude Code, claude.ai e Codex): o assistente abre uma página do DevZap, você entra com o seu usuário e autoriza. Ninguém copia chave.
• Com a chave no cabeçalho (Claude Code, Cursor e qualquer cliente que aceite cabeçalho): você cria a chave no painel e põe na configuração do cliente.

Pelo login

Na página de autorização, confira o endereço do aplicativo e para onde o acesso vai antes de autorizar. Só administradores do workspace autorizam. Ao autorizar, o DevZap cria uma chave só para aquele assistente:

• Ela só vale no servidor MCP. Usada direto na API, recebe KEY_WRONG_AUDIENCE.
• Ela vence em 90 dias. Depois disso, o assistente pede o login de novo.
• Cada pessoa tem uma chave por assistente. Fazer o login de novo com o mesmo assistente (para pedir mcp:envio, por exemplo) revoga na hora a chave anterior dessa pessoa para esse aplicativo. A chave de outro administrador continua. Dois computadores com o mesmo assistente e o mesmo usuário dividem essa chave: o login no segundo desconecta o primeiro.
• Quem sai do workspace, passa a membro comum ou tem a conta apagada perde na hora as chaves de assistente que conectou. As chaves comuns, criadas no painel, continuam.
• Ela aparece em Chaves de API com o nome do aplicativo e o endereço dele, por exemplo Claude Code (claude.ai) (OAuth), e não conta no limite de chaves do plano. Revogar essa chave desconecta o assistente.
• Por padrão, ela só consulta. Para o assistente também enviar (nos planos que incluem o envio pelo assistente), peça a permissão mcp:envio, como cada cliente explica abaixo. Quem tem mcp:envio também consulta.

Quando a chave só consulta e o assistente tenta enviar, o DevZap responde HTTP 403 insufficient_scope pedindo mcp:envio.

Claude Code e Codex, com um comando

npx devzap

O comando adiciona o DevZap ao Claude Code e ao Codex que estiverem instalados e já abre o login no navegador. Para o assistente também enviar, rode npx devzap --envio. Num DevZap em outro endereço, npx devzap --url SEU_HOST. As outras opções estão em npx devzap --ajuda.

Os comandos abaixo fazem o mesmo à mão.

Claude Code

claude mcp add --transport http --scope user devzap https://SEU_HOST/api/v1/mcp

Depois, dentro do Claude Code, rode /mcp, escolha devzap e faça o login no navegador que abrir. Do terminal, claude mcp login devzap faz o mesmo.

O Claude Code pede só os escopos fixados na configuração. Para o assistente enviar, fixe mcp:envio e faça o login de novo pelo /mcp:

claude mcp remove devzap --scope user
claude mcp add-json --scope user devzap \
  '{"type":"http","url":"https://SEU_HOST/api/v1/mcp","oauth":{"scopes":"mcp:envio"}}'

Se o envio falhar com needs additional permissions, a configuração ainda está sem mcp:envio.

Codex

codex mcp add devzap --url https://SEU_HOST/api/v1/mcp

O comando já abre o login no navegador. Para entrar de novo depois, rode codex mcp login devzap. Use uma versão recente do Codex (testado com a 0.156.1): versões antigas, como a 0.134, tentam o registro automático de cliente e param em Dynamic client registration not supported.

O Codex começa com a consulta. Para o assistente também enviar, faça o login pedindo a permissão de envio:

codex mcp login devzap --scopes mcp:envio

Para o Codex pedir a sua confirmação antes de enviar, acrescente default_tools_approval_mode = "writes" em [mcp_servers.devzap], no ~/.codex/config.toml.

claude.ai e Claude Desktop

1. Abra Customize > Connectors, clique em + Add e depois em Add custom connector. Nos planos Team e Enterprise do Claude, quem adiciona é o Owner.
2. Dê um nome (por exemplo DevZap), informe https://SEU_HOST/api/v1/mcp e clique em Continue.
3. Em Authentication, escolha Sign in when needed ou Sign in now.
4. Em OAuth client, escolha Use Claude's published identity (Recommended). A opção Register automatically não funciona com o DevZap.
5. Clique em Add e faça o login na página do DevZap.

O claude.ai começa com a consulta. Ainda não confirmamos como ele pede a permissão de envio.

Com a chave no cabeçalho

• Crie uma chave só para o assistente, em Chaves de API no painel, com um nome como Claude da equipe. A chave fica no arquivo de configuração do cliente de IA, no seu computador. Se ela vazar, revogue e crie outra: o assistente perde o acesso na hora, e os seus sistemas continuam com as chaves deles.
• Se o assistente só vai consultar, escolha o tipo de acesso "Só consulta". Essa chave lê tudo o que as ferramentas de consulta leem e não envia nem muda nada: as ferramentas de envio recusam com SCOPE_DENIED. Se ela vazar, ninguém manda mensagem em nome da conta.
• Deixe o cliente pedir a sua confirmação antes de cada envio. O assistente pode errar o destino ou o texto, e mensagem enviada não volta.

Nos exemplos, troque https://SEU_HOST pelo endereço da API e ten_sua_chave pela chave.

Claude Code

claude mcp add --transport http devzap https://SEU_HOST/api/v1/mcp \
  --header "Authorization: Bearer ten_sua_chave"

Acrescente --scope user para usar o DevZap em todos os projetos. Evite --scope project: ele grava a chave no .mcp.json do repositório.

Cursor

No arquivo ~/.cursor/mcp.json:

{
  "mcpServers": {
    "devzap": {
      "url": "https://SEU_HOST/api/v1/mcp",
      "headers": { "Authorization": "Bearer ${env:DEVZAP_CHAVE}" }
    }
  }
}

O Cursor lê a chave da variável de ambiente do seu terminal, então ela não fica no arquivo. O arquivo do projeto (.cursor/mcp.json) também funciona, mas só se estiver no .gitignore.

Codex

Com a chave na variável de ambiente DEVZAP_CHAVE do seu terminal:

codex mcp add devzap --url https://SEU_HOST/api/v1/mcp --bearer-token-env-var DEVZAP_CHAVE

O comando grava o servidor no ~/.codex/config.toml. Acrescente a linha de aprovação para o Codex pedir a sua confirmação antes de toda ferramenta que não seja de consulta:

[mcp_servers.devzap]
url = "https://SEU_HOST/api/v1/mcp"
bearer_token_env_var = "DEVZAP_CHAVE"
default_tools_approval_mode = "writes"

claude.ai e Claude Desktop

Siga os passos 1 e 2 do login. Em Authentication, escolha No sign-in. Em Request headers, escolha authorization e informe Bearer ten_sua_chave, com a palavra Bearer e o espaço. Se a seção Request headers não aparecer, conecte pelo login.

Depois de salvo, o cabeçalho não muda: para trocar a chave, remova o conector e adicione de novo. Nos planos Team e Enterprise do Claude, a chave cadastrada pelo Owner vale para todos os membros da organização.

ChatGPT

Ainda não conecta. O ChatGPT só aceita servidor MCP com login, e o login do DevZap ainda não aceita a forma como o ChatGPT se identifica. Use o Claude Code, o claude.ai, o Cursor ou o Codex.

Conferir

Peça ao assistente para usar o conta_status do DevZap. A resposta traz a conta, o plano, o que o assistente pode fazer nela e, quando não pode, o motivo.

Ferramentas

Consulta

Envio

Do jeito que você fala

Nenhuma ferramenta pede id técnico. O assistente passa o que você disse, e o DevZap resolve:

• Qual número. Com um número só na conta, ou um só conectado, ele é usado sem perguntar. Com mais de um, vale o nome dele ("o número de vendas"), o final do telefone ("final 3344") ou o id (INST-...). Na dúvida, a ferramenta recusa com as opções e o assistente pergunta.
• Telefone em qualquer formato. "(11) 12345-6789", "11 12345 6789" e "5511123456789" são o mesmo destino. Sem DDI, o número é do Brasil. Para fora do Brasil, use o + e o DDI ("+1 415 555 0100"). Sem DDD, a ferramenta pede o DDD.
• Grupo e etiqueta pelo nome. "Manda no grupo Suporte Abite", "Quem tem a etiqueta Cliente VIP". Na consulta, um trecho do nome basta se só um combinar. Para enviar e para pôr ou tirar etiqueta, o nome tem de ser o exato (sem diferenciar maiúscula nem acento): o que você aprova na tela é o nome do destino, e um trecho poderia cair num grupo parecido.

A resposta diz qual número foi usado (numeroUsado) e, no envio, para quem foi (destino). Toda resposta abre com um resumo em português ("2 números: Suporte (final 4321) conectado; Vendas (final 3344) desconectado."), com as situações traduzidas (situacao), e o assistente costuma repetir esse resumo na conversa. Os dados completos vêm logo depois.

As ferramentas que escrevem chegam ao cliente marcadas como destrutivas (destructiveHint). enviar_mensagem, enfileirar_mensagem e por_tirar_etiqueta também pedem aprovação a cada chamada: o Claude Code mostra a confirmação em todo envio e em toda etiqueta posta ou tirada, mesmo no modo automático, sem a opção de não perguntar de novo, e recusa a chamada no modo que nunca pergunta. A etiqueta entrou na lista porque o seu sistema pode reagir a ela pelo webhook label.*. Nos outros clientes, confira na configuração se ele pede confirmação antes de usá-las.

O envio pelo assistente é para quando uma pessoa acompanha. Para mandar mensagem sem ninguém aprovando, como um lembrete do seu sistema, use a API (Envio de mensagens).

Cartões na conversa

No claude.ai, no Claude Desktop, no app do celular, no ChatGPT e no VS Code, algumas respostas aparecem como um cartão dentro da conversa, no tema claro ou escuro do próprio assistente:

• conta_status: o plano, os números conectados e a barra dos envios pelo assistente hoje;
• listar_numeros: cada número com a situação em cor e, se caiu, o motivo;
• historico_de_envios: os envios como balões do WhatsApp, com os tiques (✓ enviada, ✓✓ entregue, ✓✓ azul lida);
• enviar_mensagem: a mensagem que saiu, para quem e por qual número;
• previa_da_mensagem: o balão como a mensagem vai sair e o botão Enviar. O clique passa pela confirmação do próprio assistente antes de sair, e conta no teto diário como qualquer envio. Nos clientes que não repassam o clique, a prévia mostra o balão e o assistente pede o "pode enviar" na conversa.

Quando há mais de um número e o pedido não diz qual, o cartão mostra as opções. O cartão não faz nenhuma conexão de rede: tudo que ele mostra veio na resposta da ferramenta. No Claude Code, que roda no terminal, a resposta continua em texto.

Atalhos

O DevZap publica pedidos prontos. No Claude Code, digite /devzap: e escolha; no VS Code, /mcp.devzap.. O claude.ai e o Claude Desktop ainda não mostram atalhos de conector: lá, escreva o pedido normalmente.

O que pedir

Exemplos de pedidos, em português mesmo:

• "Quais números do DevZap estão desconectados? Por que o último caiu?"
• "O número da loja está com alguma restrição do WhatsApp? Quantas conversas novas ele ainda pode abrir hoje?"
• "O que saiu para o (11) 12345-6789 nesta semana? Alguma mensagem falhou?"
• "Quem tem a etiqueta Orçamento enviado?"
• "Em quais grupos o número consegue enviar?"
• "Quais agendamentos rodam na segunda-feira?"

Para enviar, peça o texto antes e confira:

• "Escreva um lembrete curto para cada contato com a etiqueta Orçamento enviado. Não envie: me mostre os textos primeiro."
• Depois de ler: "Pode enviar os dois primeiros. O terceiro eu mando depois."

O que o plano libera

A consulta e o envio pelo assistente são duas funcionalidades do plano, mcp e mcp_escrita. Sem a funcionalidade, a ferramenta recusa com PLAN_FEATURE_NOT_ALLOWED e o nome dela em feature. Pelo mesmo motivo do guia de limites, a relação de plano × funcionalidade não fica aqui: ela está na página de planos do painel. O conta_status diz, para a sua conta, se o assistente pode consultar e enviar.

Com o plano vencido, as ferramentas recusam com o código do plano, e o conta_status continua respondendo para explicar o motivo.

Limites

• Limite por minuto do plano. Cada mensagem MCP conta 1, como uma chamada REST. Abrir a conexão, listar as ferramentas e chamar uma ferramenta são mensagens. A ferramenta chama a rota da API por dentro, sem cobrar de novo.
• Limites de envio. O envio pelo assistente passa pelo mesmo limite de mensagens por minuto da conta e pelo mesmo teto por hora de cada número da API. Um envio pelo assistente gasta do mesmo saldo que um envio do seu sistema.
• Teto diário do assistente. São 200 envios por dia por conta, somando todos os números, e o teto zera à meia-noite de Brasília. Os envios pela API e pelo painel não contam. Uma recusa antes de enviar (número desconectado, limite, validação) devolve a vaga. O conta_status mostra quanto resta.
• Limite global. Com a chave reconhecida, ele é da conta, e não do IP: outras contas que usam o mesmo assistente (e chegam pelo mesmo IP) não gastam o seu. Cada mensagem MCP conta 1 nele, e a chamada interna da ferramenta não conta de novo.

Erros

A ferramenta que falha devolve isError com code e message, e quando houver, retryAfter, upgradeUrl ou renewUrl. Os códigos são os mesmos da API (veja Erros e retry), mais estes, que são só do assistente:

Envio que deu erro de tempo ou SEND_UNCONFIRMED pode ter saído. Antes de mandar de novo, confira no historico_de_envios.

Conversas recebidas (opcional)

Por padrão, o DevZap não guarda o que os números recebem, e o assistente não lê conversas. Um administrador pode ligar a gravação das recebidas num número, no painel, em Números, depois de ler os avisos. conversas_recentes e ler_conversa só aparecem quando essa opção está disponível no DevZap, e só leem os números em que ela está ligada:

• Só conversas individuais. Grupos ficam de fora da gravação.
• Permissão própria. A chave precisa do escopo conversations:read. A chave de acesso completo do painel tem; a "Só consulta" não. Pelo login, peça a permissão mcp:conversas: no Claude Code, "oauth":{"scopes":"mcp:conversas"}; no Codex, codex mcp login devzap --scopes mcp:conversas. Para ler e enviar, peça as duas: mcp:envio mcp:conversas.
• Texto de terceiro. O que o contato escreveu chega em textoDoContato, com o aviso de que é dado, não instrução. Quem manda mensagem para o número pode escrever instruções para enganar o assistente: revise todo envio antes de aprovar.
• Desligar apaga. Ao desligar a gravação, o DevZap apaga tudo o que guardou daquele número.

O que o assistente não faz

• Ler conversas de número sem a gravação ligada. Por padrão, o DevZap não guarda o que o número recebe (veja Conversas recebidas, acima).
• Mexer na estrutura da conta. Criar ou apagar número, mostrar QR code, configurar webhook e criar, pausar ou apagar agendamento ficam no painel e na API.
• Enfileirar para grupo. A fila só aceita telefone; para grupo, o envio é direto.

Segurança

• Texto de terceiros. Nomes de grupo, de etiqueta e de contato são escritos por outras pessoas, e qualquer um pode pôr o seu número num grupo. O DevZap tira caracteres de controle desses nomes, mas o conteúdo continua sendo de outra pessoa. Confira antes de deixar o assistente enviar a partir do que ele leu.
• Registro. Cada escrita pelo assistente fica registrada com o prefixo da chave, o número, o destino com só os 4 últimos dígitos e o resultado. O texto da mensagem não vai para o registro.
• Revogar. Revogar a chave em Chaves de API corta o assistente na hora, seja ela criada à mão ou pelo login.

← Todos os guias