Skip to main content
O MCP da Zatten tem dezesseis ferramentas. Todas agem em nome da conta da agência, dentro do alcance da conexão criada no painel. Toda ferramenta aceita também intent e skill_version, dois campos opcionais para a Zatten entender o uso (ver O que a Zatten registra).

O ciclo de uso

1

list_projects

Sempre que a pessoa citar um projeto pelo nome. As outras ferramentas exigem o id e o nome exatos.
2

get_template

Guarde a revision que vier.
3

Plano e “sim”

Mostre o que vai mudar. Veja as regras.
4

update_template

Com a revision da leitura e só os blocos que mudam.
5

Leia as notes e releia o projeto

A resposta não traz a revision nova. Para registrar o estado novo (snapshot) ou editar de novo, chame get_template outra vez.

O par project_id + project_name

get_template e update_template pedem o id do projeto e o nome exato, como vieram de list_projects. O servidor confere os dois contra o banco. Se não casarem, recusa e diz de quem é o id enviado. É a trava mais barata contra mexer no cliente errado: quem confunde dois projetos erra o id ou o nome, e errar os dois do mesmo jeito é muito menos provável.

whoami

Confirma a conta conectada. Use antes de alterar qualquer coisa, para dizer à pessoa em nome de quem você está agindo.

list_projects

Os projetos que a conexão alcança, em ordem de nome. A lista é o limite da conexão: projeto que não aparece aqui não pode ser lido nem alterado, nem pelo id. Cada projeto traz, além do id e do nome, o que ajuda a se orientar: a organização (a pasta do painel), o plano, se está pago e se o WhatsApp está conectado. O detalhe (limites, uso, versões do agente) vem no get_template.

get_template

O projeto inteiro em JSON: funil, tags, propriedades, skills, automações, fluxos, templates da Meta e o agente. A referência de cada bloco está em Referência do template.
  • O config do agente vem da versão mais nova, publicada ou não. Assim quem edita não apaga um rascunho que alguém deixou no painel.
  • Todos os templates da Meta do projeto vêm no bloco meta_templates.
  • A revision é a marca do estado atual. Duas leituras sem mudança no meio devolvem a mesma; se mudou, alguém mexeu.
  • Ao lado do template vem project: as informações do projeto que não são configuração (organização, plano e uso, cobrança, WhatsApp e as versões do agente). Ver abaixo.
  • O JSON traz endereços de webhook e de MCP, headers e as chaves do agente (do modelo e do LangSmith), preenchidos. Trate-o como confidencial: nunca mostre uma chave na conversa nem a grave em arquivo. O snapshot é gravado com as chaves trocadas por "<removido>" (ver Organizar sua agência).

update_template

Aplica alterações. Cria o que falta, atualiza o que existe e nunca apaga. Envie só os blocos que vai mudar: o que não vier não é tocado. Mas o bloco enviado é declarado por inteiro, e o que existir no projeto e faltar no bloco volta como órfão. As regras completas (o que conta como “vazio”, ligar e desligar, renomear, referências por nome, o agente) estão em Como uma escrita funciona. O que update_template não faz:
  • apagar qualquer coisa;
  • publicar a versão do agente (cria uma versão nova, não publicada);
  • enviar template à Meta (o envio é pelo painel);
  • migrar o projeto de motor;
  • reescrever o desenho de um fluxo que já existe;
  • gravar llm_attendant.functions;
  • ligar a aprovação humana do agente.
Os assistentes tratam update_template como ação destrutiva e costumam pedir confirmação. Não é que apague: é que altera a configuração de um cliente real.

create_project

Cria um projeto novo na conta. Três jeitos:
  • Em branco: só o nome. Nasce como o “em branco” do painel: funil Novo Contato / Atendimento Humano / Ganho / Perdido e o departamento Atendimento.
  • Com blocos: nome + template, no mesmo formato do update_template. Cada bloco enviado substitui o do em branco por inteiro (mandar columns com três colunas dá um funil de três).
  • Duplicando: nome + source_project_id. O projeto novo nasce como cópia do outro, inclusive chaves e endereços, que são lidos no servidor e não passam pela conversa. As variáveis do prompt nascem vazias, salvo com keep_variable_values: true: o projeto novo é de outro cliente. As perguntas do gestor vão junto, e o agente só liga depois que as variáveis usadas no prompt forem preenchidas. Pergunte à pessoa qual dos dois ela quer.
Criar é livre. O projeto nasce com a assinatura pendente, o agente de IA e as automações desligados. O pagamento é cobrado quando a pessoa conectar o WhatsApp, no painel (Conexões do WhatsApp). Mesmo assim, o assistente confirma com a pessoa antes de criar: é um projeto a mais na conta dela. Em branco ou com blocos, o projeto nasce no LangChain Agent. Duplicado, fica no motor da origem. Quem pode: uma conexão de Leitura e edição que alcance todos os projetos da conta, gerada por alguém que continua admin. Uma conexão restrita a alguns projetos não cria projetos.

test_agent

Manda uma mensagem ao agente de IA do projeto, como se fosse o contato de teste no WhatsApp, e devolve o que ele respondeu, as tools que chamou (com argumentos e resultado) e o que falhou. É o chat de teste do painel, pelo MCP. É o que fecha o ciclo de construção do agente: o update_template cria uma versão nova → o test_agent roda essa versão → o assistente lê a resposta e as tools → ajusta → testa de novo. Veja Construir o agente iterando.
  • Roda a versão mais nova, publicada ou não. O WhatsApp continua na publicada até uma pessoa publicar no painel. O assistente nunca publica.
  • As tools executam de verdade. Uma tool HTTP chama o sistema do cliente (um agendamento de teste vira agendamento real); as ações da Zatten mexem no contato de teste. Antes da primeira rodada, o assistente avisa a pessoa e espera o “sim”; com ele, itera sem pedir de novo a cada rodada.
  • Conversa: a resposta traz thread_id. Mandado de volta, continua a mesma conversa de teste. Só conversas de teste do projeto são aceitas: uma conversa real de lead nunca é lida nem continuada por aqui.
  • Só no LangChain Agent, e exige conexão de Leitura e edição. Cada rodada leva até 3 minutos.
O que o chat de teste não testa (buffer, pausa humana, mídia, segmentação, automações) o test_agent também não testa.

create_organization, rename_organization e move_project

As organizações são as pastas do painel que agrupam projetos. Para a agência, costumam ser o estágio do cliente: “Prospects”, “Implantação”, “Produção”. Toda conta nasce com uma chamada “Principal”. Veja Organizações e projetos.
  • create_organization cria; nome repetido é recusado.
  • rename_organization renomeia; os projetos dela não mudam.
  • move_project move um projeto para outra organização. Funil, agente, automações e leads vão juntos, e o acesso dos membros vai junto: quem via o projeto continua vendo.
  • Apagar organização não existe pelo MCP. É no painel, com o assistente guiando.
Quem pode: criar e renomear exigem conexão de Leitura e edição com acesso a todos os projetos (organização é da conta, não de um projeto). Mover exige o projeto no alcance da conexão, como toda escrita num projeto.

find_contacts

Procura contatos (leads) de um projeto. É busca, não exportação: serve para chegar ao número de um contato e, com ele, ler a conversa pela API do dia a dia.
  • Exige pelo menos um filtro: query (parte do nome ou do número), column, tag, ou um período da última interação.
  • Devolve no máximo 20, os de interação mais recente.
  • Só identificação: nome, número, coluna, tags e datas. Nunca o conteúdo das mensagens, notas ou propriedades.
  • Até 30 buscas por minuto por conexão.
Para a base inteira, a pessoa exporta o CSV no painel (Contatos → Exportar).

get_metrics

Os números de um projeto num mês, os mesmos da tela de Métricas (Métricas), pela mesma conta: contatos novos (anúncio x orgânico), mensagens recebidas e enviadas, mensagens da IA x de humanos, tokens, o funil por coluna, os anúncios que trouxeram contatos e as conversões. Total e por dia. Para avaliar como um agente está indo, montar o relatório mensal do cliente final ou mostrar resultado numa renovação (Operar a agência).

list_members

Os membros da conta: nome, e-mail, papel, os projetos que cada um vê e os departamentos em que está, com se recebe os leads de cada um. Para diagnosticar acesso (“por que a Ana não vê o projeto da clínica?”, “quem recebe os leads do Comercial?”) e para ler antes de mudar.

create_member e update_member_access

Criam membros e mudam o acesso deles, com as mesmas regras de Configurações → Gerenciar Acessos (Usuários e permissões).
  • create_member cria o login com nome, e-mail, senha e papel (Gestor, Editor ou Visualizador). O membro nasce sem projetos.
  • update_member_access muda, pelo e-mail, o papel, o nome, a senha, os projetos e os departamentos de um membro. Só muda o que vier: projeto ou departamento que não está no pedido fica como está.
  • “Recebe leads” é por departamento, não do membro: a mesma pessoa pode receber no Comercial e não no Suporte.
  • Entrar num departamento libera o projeto. Tirar o projeto (access: false) tira o membro dos departamentos dele.
  • A senha é a que a pessoa escolher: o assistente pergunta. O white label não tem “esqueci a senha”, então trocar a senha também é por aqui (ou no painel). A senha nunca volta na resposta e não entra no registro de uso.
Tudo ou nada. O pedido é recusado inteiro, sem mudar nada, quando:
  • o departamento não existe no projeto (a recusa lista os que existem);
  • o membro tem leads atribuídos num departamento de onde sairia;
  • o departamento ficaria sem ninguém recebendo leads;
  • o projeto chegou ao limite de usuários do plano.
Só no painel: criar ou promover Admin, trocar papel ou senha de um Admin, e remover um membro da conta. Departamento novo se cria pelo update_template (bloco attendant_teams). Quem pode: conexão de Leitura e edição, com acesso a todos os projetos, gerada por um Admin da conta.

get_white_label

A configuração de white label da conta (não de um projeto): nome da marca, subdomínio e endereço do painel, domínio próprio, logo, favicon, cores e contato. Veja White label. Só leitura. Mudar marca ou domínio é com a pessoa, em Configurações → Minha Empresa e Configurações → Domínios Customizados. Se o domínio próprio está verificado, é a segunda tela que diz.

send_feedback

Conta à Zatten como terminou a tarefa que a pessoa pediu: feita, feita em parte ou travada, e onde travou. Não muda nada no projeto e não aparece para a pessoa: é o que a Zatten usa para melhorar a skill, esta doc e as ferramentas. O assistente chama uma vez no fim de cada tarefa que usou o MCP.

O que a Zatten registra

Cada chamada ao MCP deixa um registro de uso do lado da Zatten, para melhorar a skill, a doc e as ferramentas:
  • a ferramenta, o projeto, se deu certo e quanto tempo levou;
  • o assistente que chamou (Claude Code, Codex…), pelo nome que ele informa;
  • um resumo sem dado do cliente: quais blocos foram enviados, quantas mudanças e órfãos, quais tools o agente chamou num teste;
  • o intent e o send_feedback, quando o assistente os manda.
Nunca entram o template, chaves, endereços ou o conteúdo de mensagens. Os registros ficam 3 meses e não aparecem no painel.

Erros

Quando a operação é recusada, nada é alterado. As mensagens dizem o que fazer:

Armadilhas

  • ok: true não quer dizer que tudo foi feito. Recusas parciais (automação que não ligou por falta de endereço, conversão cuja coluna não existe, template da Meta não enviado) aparecem só nas notes.
  • A revision não vem na resposta da escrita. Duas escritas seguidas com a mesma revision: a segunda é recusada, porque a primeira já mudou o projeto.
  • Texto de exemplo numa chave do langchain.config grava por cima. Chave ausente, null ou "" mantém a atual; "<removido>" ou "sk-..." substitui e derruba o agente. Devolva o valor lido ou omita o campo.
  • project não é configuração. Não devolva o bloco project do get_template no update_template: ele é só leitura e fica fora do template.
  • Testar executa. O test_agent roda as tools do agente de verdade. Uma tool que mexe em sistema externo age nele.
  • Renomear o projeto muda o par. Se o bloco meta trocar o nome do projeto, a próxima chamada precisa do nome novo.
  • A senha do membro é segredo. Pergunte qual é, nunca invente e nunca a repita (plano, chat, arquivo, memória, intent). Ela não volta na resposta.
  • Membro novo não vê nada. O create_member cria sem projetos; o acesso vem no update_member_access.
  • A nota sobre templates da Meta cita uma opção que o MCP não tem. Quando faltam templates, a nota sugere submit_meta_templates: true. Pelo MCP essa opção não existe: o envio à Meta é feito por uma pessoa, no painel (WhatsApp → Templates).

Para saber mais