API Reference/MCP Server

MCP Server

Conecte o CrazyLeads diretamente a assistentes de IA como Claude, Cursor ou qualquer cliente compativel com o Model Context Protocol (MCP). Consulte leads, crie dashboards, gere SQL, gerencie datasets e adicione gráficos usando linguagem natural.

Como Conectar

O CrazyLeads MCP é um servidor HTTPS com autenticação via OAuth 2.1. Você não precisa instalar pacotes nem gerenciar API keys — basta adicionar a URL do servidor no seu cliente e fazer login na sua conta CrazyLeads quando o cliente pedir.

Campo	Valor
URL do servidor	`https://mcp.crazyleads.com.br/mcp`
Transporte	Streamable HTTP
Autenticação	OAuth 2.1 (PKCE + Dynamic Client Registration)
Escopos	`mcp:read` `mcp:write`

O fluxo de login abre uma aba do navegador, você escolhe o projeto que a IA poderá acessar e autoriza. O token fica salvo no cliente — não há API key pra rotacionar.

Claude Desktop

Abra Settings → Connectors, clique em Add custom connector e cole a URL:

https://mcp.crazyleads.com.br/mcp

O Claude abre o login do CrazyLeads no navegador. Após autorizar, selecione o projeto na tela de consentimento. O conector aparece com status Connected e as 75 tools ficam disponíveis na conversa.

Claude.ai (Web)

Em claude.ai/settings/connectors, escolha Add custom connector e use a mesma URL acima. O fluxo de autorizacao e identico ao do Desktop.

Disponível em planos Pro, Team e Enterprise.

Claude Code (CLI)

Adicione o servidor pelo CLI — o Claude Code cuida do fluxo OAuth no primeiro uso:

claude mcp add --transport http crazyleads https://mcp.crazyleads.com.br/mcp

Use --scope user pra disponibilizar em todos seus projetos, ou --scope project pra compartilhar com a equipe (gera um .mcp.json no repo).

Pra checar o status ou reautenticar: /mcp dentro do Claude Code.

ChatGPT

No ChatGPT (plano Plus, Pro, Business ou Enterprise), abra Settings → Connectors → Add e selecione Custom MCP server. Use:

https://mcp.crazyleads.com.br/mcp

Autorize com sua conta CrazyLeads na janela que abrir e escolha o projeto. As tools ficam disponíveis dentro de conversas e em Deep Research.

Cursor

Adicione ao ~/.cursor/mcp.json (global) ou .cursor/mcp.json (no projeto):

.cursor/mcp.json

{
  "mcpServers": {
    "crazyleads": {
      "url": "https://mcp.crazyleads.com.br/mcp"
    }
  }
}

O Cursor detecta o servidor e abre o fluxo OAuth automaticamente na primeira chamada.

Outros Clientes MCP

Qualquer cliente compativel com a especificacao Model Context Protocol (transporte Streamable HTTP + OAuth 2.1) funciona — basta apontar pra https://mcp.crazyleads.com.br/mcp. O servidor expõe as metadatas exigidas pelo padrão:

/.well-known/oauth-protected-resource — descobre o servidor de autorizacao
https://crazyleads.com.br/.well-known/oauth-authorization-server — endpoints OAuth (authorize, token, register, revoke)

O cliente registra-se sozinho via Dynamic Client Registration (RFC 7591) — não há cadastro manual de aplicação.

Projeto Ativo

O token OAuth fica vinculado a um projeto ativo — o que você selecionou na tela de consentimento. Todas as tools operam sobre esse projeto.

Use get_active_project pra ver qual projeto a IA está usando agora.
Use list_projects pra ver todos os projetos a que você tem acesso.
Use set_active_project pra trocar de projeto dentro da mesma conversa — sem precisar reautenticar.

Treinamento da IA via MCP

O MCP Server envia automaticamente um conjunto completo de instruções para a IA, ensinando-a a trabalhar com seus dados de forma inteligente. A IA recebe treinamento sobre:

Data Discovery Automático

A IA e treinada para investigar antes de construir. Antes de criar qualquer dashboard, ela executa queries exploratórias automaticamente para descobrir:

Produtos distintos e suas frequencias (Hotmart)
Campanhas, adsets e distribuição de gastos (Facebook/Google Ads)
UTM sources, campaigns e mediums (Pixel/Page Events)
Padrões de nomenclatura entre fontes de dados
Campos disponíveis e seus tipos por fonte

Fontes de Dados

A IA conhece todas as fontes de dados do CrazyLeads e sabe como usar cada uma:

Pixel / Page Events — trafego, pageviews, sessoes, UTMs, funis
Hotmart / Payment — vendas, receita, reembolsos, comissões, multi-moeda
Facebook Ads — gastos, impressões, cliques, CTR, CPC, conversões
Google Ads — campanhas de search, display, video
Conversions — eventos de conversão customizados
Custom SQL — queries cruzadas entre fontes
Datasets — tabelas customizadas para dados externos

Regras de Negócio

A IA e treinada com regras criticas do dominio:

Vendas Hotmart: status IN ('APPROVED', 'COMPLETE') apenas
Receita: usa commission_producer_value (não price_value)
Multi-moeda: nunca mistura BRL + USD em um SUM
list_tables primeiro: descobrir o dado antes de escrever SQL
test_sql antes de afirmar: nunca adivinhar grafias de status ou nomes de campos
Guias de autoria: artefatos, Envios e experimentos têm guia próprio, lido antes do primeiro create

Analise Cross-Source

A IA sabe combinar dados de fontes diferentes para criar métricas cruzadas:

CPA: SUM(facebook.spend) / COUNT(hotmart.sales)
ROAS: SUM(hotmart.revenue) / SUM(facebook.spend)
Taxa de Conversão: COUNT(conversions) / COUNT(DISTINCT page.visitors)
Virtual fields unificados: coluna 'produto' consistente entre Hotmart, Facebook e Pages

Artefatos e Apresentação

A IA segue o guia de autoria dos artefatos ao montar relatórios:

KPIs primeiro, série temporal no meio, tabela de detalhe por último
Formatação por tipo de grandeza (R$, %, inteiros) definida nas queries
Uma query por pergunta, nomeada por slug — edição reconcilia por slug
Publicação e compartilhamento só quando o usuário pede

Fluxo de Criação de Relatório (artefato)

Para criar um relatório/dashboard vivo, a IA segue esta ordem:

Descobrir dados disponíveis

list_tables mostra as tabelas e colunas do projeto — sempre o primeiro passo.

Entender o contexto

A IA pergunta sobre o negócio: quais produtos, como agrupar campanhas, quais métricas importam.

Explorar e validar

test_sql roda queries exploratórias contra o dado real: valores distintos, grafias de status, distribuição.

Ler o guia de autoria

get_artifact_authoring_guide traz o contrato de queries, layout e boas práticas do artefato.

Criar o artefato

create_artifact com as queries validadas. O resultado é uma página viva, hospedada, com link compartilhável (publish_artifact / share_artifact).

Editar com segurança

get_artifact lê a definição atual; update_artifact reconcilia as queries POR SLUG — sempre reenvie o conjunto completo.

Todas as ferramentas

São 120 ferramentas, agrupadas por assunto. As marcadas com escreve alteram alguma coisa — criam, editam, apagam ou disparam — e só funcionam com o escopo mcp:write. As demais só leem. Se você conectar em modo somente leitura, as de escrita simplesmente não aparecem para o assistente.

Leads (5)

count_leads	Conta quantos leads casam com os filtros dados, sem trazer os registros.
get_lead	Devolve o detalhe completo de um lead: e-mails, telefones, dispositivos, endereços, atributos por namespace, dados de merge e estatísticas.
get_lead_timeline	Devolve a linha do tempo de atividades do lead — pageviews, compras, conversões e outros eventos, com UTM e dados da transação.
list_leads	Lista leads do projeto com filtros e paginação, devolvendo dados de resumo (nome, e-mail, telefone, status, datas).
search_leads	Busca leads por nome, e-mail ou telefone e devolve os que casarem com dados de resumo.

Dados e SQL (2)

list_tables	Lista as tabelas e colunas disponíveis do projeto a partir do catálogo de Fontes; é a chamada a fazer antes de escrever qualquer SQL.
test_sql	Executa um SQL com LIMIT 100 e devolve a amostra, para explorar dados e validar a consulta antes de ligá-la a um artefato.

Datasets (17)

get_dataset	Devolve o detalhe de um dataset, incluindo esquema (colunas e índices) e informação de versão.
get_dataset_count	Conta as linhas de um dataset, com filtro opcional.
get_dataset_schema	Devolve o esquema atual do dataset (colunas e índices).
list_datasets	Lista os datasets do projeto com id, slug, nome, descrição, classe de armazenamento, versão atual e resumo do esquema.
query_dataset_rows	Consulta linhas do dataset com filtro, ordenação e paginação por cursor; devolve linhas, total e metadados do esquema.
add_dataset_columnescreve	Acrescenta uma coluna ao dataset criando uma versão rascunho, que só passa a valer com publish_dataset_version.
create_datasetescreve	Cria um dataset com a definição de esquema; a ativação exige publish_dataset_version em seguida.
delete_datasetescreve	Desativa o dataset (soft delete) — ele não é removido fisicamente.
delete_dataset_rowsescreve	Apaga linhas do dataset pelos UUIDs informados.
import_csv_to_datasetescreve	Lê um CSV do sistema de arquivos local e o carrega em lotes num dataset existente, com mapeamento opcional de cabeçalhos para colunas.
publish_dataset_versionescreve	Publica as mudanças de esquema pendentes do rascunho, aplicando todas de uma vez.
remove_dataset_columnescreve	Remove uma coluna criando versão rascunho; ao publicar, o dado daquela coluna é perdido de forma permanente.
rollback_dataset_versionescreve	Volta o dataset para um número de versão anterior.
smart_import_csvescreve	Lê um CSV local, infere nomes e tipos das colunas, cria um dataset novo e importa todos os dados.
update_datasetescreve	Altera os metadados do dataset (nome e/ou descrição).
update_dataset_columnescreve	Altera uma coluna com mudanças seguras (ordem, valor padrão, afrouxar restrições), sem criar versão nova.
upsert_dataset_rowsescreve	Insere ou atualiza linhas do dataset (até 1000 por chamada), decidindo por presença e existência do campo id.

Audiências (11)

get_audience	Devolve uma audiência por inteiro: segmento, revisão publicada, regra autoral, features ocultas, membros, última execução e histórico.
get_audience_authoring_guide	Devolve o guia de autoria de Audiências, com a gramática da regra e os casos de uso mais comuns do mercado.
get_audience_status	Devolve o estado operacional de uma audiência: membros, última execução, trabalho na fila, destinos de lista e assinaturas de evento.
list_audience_events	Devolve o catálogo de eventos MEDIDOS do projeto nos últimos 30 dias, em todas as fontes — a matéria-prima para escrever a regra da audiência.
list_audiences	Lista as audiências do projeto, uma linha compacta cada: id, nome, slug, status, membros, estado derivado, última sincronização e destinos ligados.
add_audience_destinationescreve	Liga a audiência a um destino existente — modo lista (audiência da Meta) ou modo evento (entrada/saída viram eventos).
create_audienceescreve	Cria uma audiência a partir de uma regra autoral, validando a árvore e conferindo cada tipo de evento contra o catálogo medido do projeto.
delete_audienceescreve	Apaga uma audiência de forma assíncrona e irreversível; sem confirmação explícita a chamada devolve apenas a simulação.
remove_audience_destinationescreve	Desliga um destino da audiência; no modo lista a audiência da Meta não é esvaziada, apenas para de espelhar.
sync_audience_nowescreve	Agenda uma execução imediata: recalcula a audiência, ou roda um destino de lista específico, ou força reenvio completo da lista.
update_audienceescreve	Altera uma audiência por PATCH; trocar a regra cria uma revisão nova e a troca de membros ocorre ao fim do recálculo.

Jornadas (10)

get_journey	Devolve a jornada completa: metadados, a definição a editar e o histórico de revisões.
get_journey_authoring_guide	Devolve o guia de autoria de Jornadas: gramática do gatilho, todos os tipos de passo e o conteúdo que cada canal aceita.
get_journey_log	Devolve a trilha de decisão por pessoa: por que entrou, que caminho tomou, o que foi enviado e o que falhou (retenção de 90 dias).
get_journey_stats	Devolve o funil por passo, as entradas por gatilho e as contagens por ramificação.
list_journeys	Lista as jornadas do projeto com id, nome, status (rascunho/ativa/pausada), se há revisão publicada e contadores.
create_journeyescreve	Cria uma jornada e, por padrão, a publica; aceita todos os passos do motor (ação, espera, atributo, ramificação, retenção e divisão aleatória).
pause_journeyescreve	Pausa a jornada: ninguém novo entra, e quem está em curso estaciona mantendo a data de vencimento.
publish_journeyescreve	Publica a revisão rascunho corrente; quem já está em curso segue na revisão em que entrou.
resume_journeyescreve	Retoma uma jornada pausada: as entradas reabrem e as instâncias estacionadas voltam a rodar.
update_journeyescreve	Atualiza uma jornada — a definição SUBSTITUI a árvore inteira, então é preciso reenviar tudo, inclusive a regra de reentrada.

Envios (9)

get_envio	Devolve um Envio por inteiro: a assinatura do destino com o mapeamento e o código de transformação, e a conversão signal-only por trás dele.
get_envio_authoring_guide	Devolve o guia de autoria de Envios: o que é um Envio, o fluxo exato de 4 chamadas para criá-lo e a gramática do filtro.
get_envio_deliveries	Inspeciona as entregas recentes de um destino: status, evento de origem, horário, código HTTP e mensagem de erro por linha.
get_envio_param_coverage	Mede, nas últimas N entregas reais de um Envio, com que frequência cada parâmetro chegou ao destino (só os nomes das chaves, nunca os valores).
get_envio_stats	Agrega as contagens de entrega de um destino numa janela de tempo, por evento de origem: enviadas, falhas, puladas e mortas.
get_event_samples	Abre os últimos eventos resolvidos reais dos tipos indicados, sem redação, mais o perfil de cobertura de chaves.
list_envios	Lista os Envios do projeto varrendo todos os destinos, uma linha compacta por Envio.
create_envioescreve	Cria um Envio — encaminha eventos resolvidos que casem com o filtro para um destino existente (Meta CAPI ou webhook).
update_envioescreve	Atualiza um Envio existente sem o assistente: nome, eventos de origem, escopo, evento de destino, mapeamento, filtro e/ou habilitação.

Destinos (7)

get_destination	Devolve um destino por inteiro: configuração, se há credencial no cofre, estado do disjuntor e saúde — nunca o segredo em si.
get_destination_health	Devolve a saúde de entrega de um destino em todos os seus Envios: veredito, contagens, taxa de sucesso, credencial e estado do disjuntor.
list_destinations	Lista os destinos de entrega do projeto (Meta CAPI, webhooks) com resumo compacto por destino.
create_destinationescreve	DEPRECIADA pela própria descrição — criava o destino sem o token; o caminho indicado é request_credentials com kind="destination".
reactivate_destinationescreve	Reconecta um destino após conserto de credencial: testa a conexão e, se passar, zera o disjuntor e reenfileira as entregas retidas.
test_destinationescreve	Envia UM evento sintético pelo destino para provar que conexão e credencial funcionam, devolvendo sucesso e status HTTP.
update_destinationescreve	Atualiza um destino (nome, habilitação e configuração); esta tool nunca aceita tokens ou segredos.

Artefatos (10)

get_artifact	Lê a definição atual de um artefato: metadados e as consultas ligadas a ele com o SQL corrente, na ordem do template.
get_artifact_authoring_guide	Devolve o guia de autoria de artefatos HTML vivos: modelo de dados CUBE, cross-filter no cliente, filtros múltiplos e layout livre em HTML/SVG.
list_artifacts	Lista os artefatos do projeto ativo com status (rascunho/vivo/arquivado), tipo e, para painéis, a contagem de filhos.
suggest_model	Deriva um rascunho de modelo semântico a partir do SQL das consultas do artefato, com confiança por campo.
validate_model	Valida um modelo semântico contra os cubos materializados atuais do artefato e devolve o total de cada medida e a contagem de linhas.
create_artifactescreve	Cria um artefato publicável — uma visualização hospedada e viva, servida por consulta própria.
delete_artifactescreve	Apaga um artefato em duas etapas: a chamada padrão devolve o relatório de impacto e só com confirmação a exclusão acontece.
publish_artifactescreve	Publica o artefato: materializa as consultas no data lake, agenda a atualização automática e passa o status para "vivo".
share_artifactescreve	Liga ou revoga o link público sem login de um artefato já publicado, devolvendo a URL compartilhável quando ligado.
update_artifactescreve	Edita um artefato no lugar, preservando identidade e link público, por patch de HTML e/ou de consultas.

Experimentos (10)

get_experiment	Devolve a definição completa de um experimento A/B, incluindo segmentação e cada variante com peso e aplicação.
get_experiment_authoring_guide	Devolve o guia de autoria de experimentos A/B: como o motor decide a variante, como escrever a segmentação e quando usar DOM ou redirecionamento.
get_experiment_report	Devolve o resultado do experimento: totais, exposições e conversões por variante, ganho sobre o controle, confiança e vencedor declarado.
list_experiment_events	Lista os nomes de evento que o projeto recebeu na janela — a união dos eventos de pixel e de webhook — para montar o funil secundário.
list_experiments	Lista os experimentos A/B do projeto de forma compacta: id, chave, nome, status, pixel, alocação, evento-meta e variantes.
list_purchase_products	Lista os produtos Hotmart reais do projeto com quantas vendas aprovadas cada um fez na janela, para apontar a meta de compra a UM produto.
activate_experimentescreve	Ativa o experimento e republica a configuração do pixel, de modo que os visitantes passem a ser distribuídos entre as variantes.
create_experimentescreve	Cria um experimento A/B; o pixel passa a servir uma versão da página por visitante e mede qual vence, incluindo compras do lado do servidor.
pause_experimentescreve	Pausa um experimento em execução e republica a configuração do pixel; o já coletado é preservado.
update_experimentescreve	Edita um experimento existente por PATCH: nome, hipótese, status, alocação, segmentação, variantes ou meta.

Campos e regras de lead (12)

get_lead_field_coverage	Mostra quantos leads têm cada campo personalizado preenchido e quando foi a última escrita.
get_lead_fields_authoring_guide	Devolve o guia de autoria de campos personalizados de lead e das regras que os preenchem, com a gramática das condições.
get_lead_rule_writes	Mostra QUEM a regra tocou — os leads mais recentes que ela preencheu, com status por linha.
list_lead_fields	Lista os campos personalizados de lead declarados no projeto (ativos e inativos) mais as regras internas que o sistema já preenche sozinho.
list_lead_rules	Lista as regras de atributo de lead do projeto na ordem de execução, com condição, campo de destino, valor e telemetria de 24 h.
test_lead_rule	Prova uma regra contra eventos reais recentes sem criar nem escrever nada, devolvendo quantos casariam e o valor que seria gravado.
create_lead_fieldescreve	Declara um campo personalizado de lead; ele só é registrado, e nada é escrito nele enquanto não houver regra apontando para o campo.
create_lead_ruleescreve	Cria a regra que preenche um campo personalizado de lead: quando um evento casar com a condição, escreve o valor no campo.
delete_lead_fieldescreve	Desativa um campo personalizado de lead: nada é apagado, os valores já escritos permanecem no histórico de cada lead.
delete_lead_ruleescreve	Apaga uma regra de atributo de lead de vez; os valores já escritos nos leads não são tocados.
update_lead_fieldescreve	Edita um campo personalizado de lead (nome, descrição, modo primeiro/último toque ou ativação); a chave é imutável.
update_lead_ruleescreve	Edita uma regra de atributo de lead; argumentos omitidos ficam intactos e a condição é validada com a mesma gramática da criação.

Integrações (6)

get_integration	Devolve o detalhe de uma integração pelo id.
list_integrations	Lista as integrações conectadas ao projeto ativo.
create_integrationescreve	Cria uma integração; exige projeto, nome, tipo, configurações e slug.
delete_integrationescreve	Apaga uma integração (operação destrutiva).
trigger_integration_syncescreve	Dispara uma sincronização manual; hoje só o tipo "tally" é suportado.
update_integrationescreve	Atualiza uma integração existente.

Fonte de banco de dados (4)

list_database_tables	Lista as tabelas do Postgres do cliente por trás de uma fonte DATABASE: schema, tabela, chave primária e contagem estimada de linhas.
test_database_query	Pré-visualiza um SQL contra o Postgres do cliente e devolve as colunas e uma amostra de até 50 linhas, sem salvar nada.
add_database_queryescreve	Acrescenta uma consulta a uma fonte DATABASE: o SQL é pré-visualizado, validado e salvo, e cada sincronização o materializa como tabela.
create_database_sourceescreve	DEPRECIADA pela própria descrição — criava a fonte sem a senha; o caminho indicado é request_credentials com kind="source:database".

Pixel e captura de formulário (3)

get_form_capture	Lê a configuração de captura de formulário do pixel no projeto: captura automática, captura por atributo e as regras de campo do projeto.
suggest_form_capture	Analisa uma página (por URL ou HTML colado) e mapeia os campos do formulário, separando o que o pixel já captura do que precisa de regra.
set_form_captureescreve	Configura a captura de formulário do pixel: as regras de campo do projeto, que mapeiam inputs para nome, telefone, e-mail e afins.

Credenciais (3)

get_credential_request	Consulta o que aconteceu com um pedido de credencial: pendente, reservado, concluído (com o recurso criado), expirado ou cancelado.
cancel_credential_requestescreve	Encerra um link de pedido de credencial antes de ele expirar; só pedidos ainda pendentes ou reservados podem ser cancelados.
request_credentialsescreve	Pede que a pessoa termine de criar uma fonte, destino ou integração dentro do CrazyLeads — o caminho para tudo que exige segredo ou login OAuth.

Projeto e membros (11)

get_active_project	Devolve o projeto ativo da sessão corrente.
list_invites	Lista os convites pendentes do projeto.
list_members	Lista os membros do projeto com seus papéis.
list_projects	Lista os projetos a que a pessoa tem acesso — o ponto de partida antes de trocar o projeto ativo.
cancel_inviteescreve	Cancela um convite pendente.
create_projectescreve	Cria um projeto; a pessoa autenticada passa a ser a dona (OWNER).
invite_memberescreve	Convida uma pessoa para o projeto por e-mail; exige papel OWNER ou ADMIN.
remove_memberescreve	Remove um membro do projeto; exige papel OWNER ou ADMIN.
set_active_projectescreve	Troca o projeto ativo deste token; as chamadas seguintes passam a operar nesse projeto.
update_member_roleescreve	Muda o papel de um membro; exige papel OWNER e não permite rebaixar o último OWNER.
update_projectescreve	Altera os metadados do projeto; exige papel OWNER ou ADMIN.

Exemplos de Uso com IA

Com o MCP server conectado, você pode fazer perguntas em linguagem natural:

›“Quantos leads ativos eu tenho?”

›“Me mostra os últimos 10 leads que fizeram uma compra”

›“Busca o lead com email joao@email.com e me mostra o histórico dele”

›“Quais leads do Brasil foram criados na última semana?”

›“Me mostra quais tabelas e colunas estão disponíveis”

›“Quantas vendas aprovadas esse mês, por produto?”

›“Cria um relatório com os gastos do Facebook Ads dos últimos 30 dias”

›“Configura um envio de Purchase para o Meta CAPI, só venda aprovada”

›“Qual a cobertura de fbc e fbp nas entregas do meu destino Meta?”

›“Roda um teste A/B trocando o título da página de vendas”

›“Importa esse CSV como um novo dataset”

O assistente de IA chama as tools certas, combina resultados e apresenta o dado de forma legível. O servidor MCP ensina à IA as regras de negócio (o que é venda aprovada, como medir antes de mapear) e as boas práticas de artefatos, Envios e experimentos.