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.

CampoValor
URL do servidorhttps://mcp.crazyleads.com.br/mcp
TransporteStreamable HTTP
AutenticaçãoOAuth 2.1 (PKCE + Dynamic Client Registration)
Escoposmcp: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:

1

Descobrir dados disponíveis

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

2

Entender o contexto

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

3

Explorar e validar

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

4

Ler o guia de autoria

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

5

Criar o artefato

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

6

Editar com segurança

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


Tools de Leads

Consulte, busque e analise seus leads com filtros avançados.

list_leads

Lista leads com filtros avançados e paginacao. Retorna dados resumidos de cada lead (nome, email, telefone, status, datas).

limitnumber1-200, padrão 20
offsetnumberOffset para paginacao
order_bystring[]Ordenação (ex: ["-created_at"]). Padrão: mais recentes
statusstringactive, merged_into, archived
emailstringFiltro por email (contains)
phonestringFiltro por telefone (contains)
namestringFiltro por nome (contains)
countrystringCódigo do país (BR, US...)
has_emailbooleanFiltra leads com email
has_phonebooleanFiltra leads com telefone
created_afterstringData ISO 8601
created_beforestringData ISO 8601
segment_idstringUUID do segmento
feature_idstringUUID da feature
get_lead

Retorna detalhe completo de um lead: emails, telefones, devices, endereços, atributos por namespace, merge info e estatísticas.

lead_idstringUUID do lead
get_lead_timeline

Retorna timeline de atividades do lead: pageviews, purchases, conversions e outros eventos com dados de UTM e transação.

lead_idstringUUID do lead
limitnumber1-200, padrão 50
offsetnumberOffset para paginacao
activity_typesstringTipos separados por virgula (pageview,purchase...)
start_datestringData ISO 8601
end_datestringData ISO 8601
search_leads

Busca leads por nome, email ou telefone (OR-based matching). Retorna leads com dados resumidos.

querystringTexto para buscar em nome, email e telefone
limitnumber1-100, padrão 10
count_leads

Conta total de leads com filtros. Útil para estatísticas rápidas sem buscar dados completos.

statusstringactive, merged_into, archived
has_emailbooleanFiltra por tem email
has_phonebooleanFiltra por tem telefone
countrystringCódigo do país
created_afterstringData ISO 8601
created_beforestringData ISO 8601
segment_idstringUUID do segmento
feature_idstringUUID da feature

Tools de Projetos, Membros e Integrações

Gerencie projetos, membros do time e integrações (fontes de dados) direto da IA. Todas operam no contexto do projeto ativo, exceto as de projeto que listam/criam workspaces.

Projetos

list_projects

Lista todos os projetos a que você tem acesso, com nome, slug e role.

get_active_project

Retorna qual projeto a IA está usando agora (vinculado ao token OAuth da sessão).

set_active_project

Troca o projeto ativo da sessão para outro projeto onde você é membro. Útil pra alternar entre projetos sem reautenticar.

project_idstringUUID do projeto destino
create_project

Cria um novo projeto e te coloca como owner.

namestringNome do projeto
slugstringSlug (opcional, gerado a partir do nome)
update_project

Atualiza nome e/ou slug do projeto ativo. Requer role admin ou owner.

namestringNovo nome
slugstringNovo slug

Membros

list_members

Lista membros ativos do projeto com email, nome e role.

invite_member

Envia convite por email para outra pessoa entrar no projeto.

emailstringEmail do convidado
roleenumowner, admin, editor, viewer
list_invites

Lista convites pendentes do projeto.

cancel_invite

Cancela um convite pendente.

invite_idstringUUID do convite
update_member_role

Altera a role de um membro existente. Requer role admin ou owner.

member_idstringUUID do membro
roleenumowner, admin, editor, viewer
remove_member

Remove um membro do projeto. Requer role admin ou owner.

member_idstringUUID do membro

Integrações

list_integrations

Lista todas as integrações do projeto ativo (Hotmart, Facebook Ads, Google Ads, Pixel, etc.) com status de sync.

get_integration

Retorna detalhes de uma integração, incluindo config, última sincronização e estatísticas.

integration_idstringUUID da integração
create_integration

Cria uma nova integração no projeto ativo. O fluxo de autorizacao (OAuth do provider, webhook secret) deve ser completado pela UI depois.

providerenumhotmart, facebook_ads, google_ads, pixel, conversion, activecampaign, generic_webhook, tally...
namestringNome amigavel
configobjectConfig específica do provider (account_id, tracking ID, etc.)
update_integration

Atualiza nome ou config de uma integração.

integration_idstringUUID da integração
namestringNovo nome
configobjectNovo config (partial)
delete_integration

Remove uma integração. Dados ja importados permanecem; sync futuro para.

integration_idstringUUID da integração
trigger_integration_sync

Dispara uma sincronização manual de uma integração. Útil pra puxar dados recentes sem esperar o cron.

integration_idstringUUID da integração

Tools de SQL

Explore as tabelas do projeto e valide SQL contra o dado real antes de usá-lo num artefato.

list_tables

Lista todas as tabelas e colunas disponíveis no projeto. Nomes seguem o padrão {type}_{slug} (ex: hotmart_htm_rtg, page_events).

SEMPRE chame esta tool primeiro, antes de escrever SQL.

test_sql

Testa uma query SQL com LIMIT e retorna resultados de amostra. Use nomes reais de tabelas de list_tables. Para vendas, filtre por status IN ('APPROVED', 'COMPLETE').

sqlstringQuery SQL para testar
start_datestringData início (YYYY-MM-DD)
end_datestringData fim (YYYY-MM-DD)

Tools de Artefatos (relatórios e dashboards)

Dashboards e relatórios são artefatos: páginas vivas, hospedadas, renderizadas sobre queries SQL — criadas e editadas pela conversa. As tools antigas de dashboard/gráfico/aba foram descontinuadas e substituídas por este fluxo.

get_artifact_authoring_guide

Guia de autoria de artefatos. SEMPRE chame antes do primeiro create_artifact — traz o contrato de queries, layout e boas práticas.

create_artifact

Cria um artefato vivo (relatório/dashboard) com um conjunto de queries SQL nomeadas por slug e um template de renderização.

get_artifact

Lê a definição completa (queries por slug e, opcionalmente, o HTML) de um artefato existente — o par de leitura do update.

update_artifact

Atualiza um artefato. Reconcilia as queries POR SLUG e apaga as órfãs: sempre leia com get_artifact e reenvie o conjunto completo.

publish_artifact

Publica o artefato com link compartilhável; list_artifacts, share_artifact e delete_artifact completam o ciclo de vida.

Tools de Envios (destinos)

Encaminhe eventos resolvidos do CDP para Meta CAPI, webhooks e demais destinos — com filtro, mapeamento e validação contra eventos reais.

get_envio_authoring_guide

Guia de autoria de Envios. SEMPRE chame antes do primeiro create_envio.

create_envio

Cria um Envio (conversão + assinatura no destino). Aceita dry_run para validar tudo sem escrever nada, e devolve o teste do filtro contra eventos reais.

get_event_samples

Amostras REAIS do payload resolvido por evento — meça o que chega ANTES de mapear ou filtrar.

get_envio_deliveries

Entregas recentes de um Envio; get_envio_stats e get_envio_param_coverage cobrem saúde e cobertura de parâmetros (em, ph, fbc, fbp).

list_destinations

Destinos do projeto; create_destination, update_destination, test_destination, get_destination_health e reactivate_destination completam o ciclo.

Tools de Experimentos (A/B)

O pixel serve variantes por visitante (bucketing estável) e mede o vencedor — incluindo compra server-side casada por identidade.

get_experiment_authoring_guide

Guia de autoria. SEMPRE chame antes do primeiro create_experiment.

create_experiment

Cria o experimento (targeting, variantes com operações de DOM ou redirect, meta de conversão). activate_experiment liga; pause_experiment pausa.

get_experiment_report

Relatório com exposições, conversões, confiança bayesiana e vencedor; aceita recorte por página e eventos secundários.

list_purchase_products

Produtos com venda no período — copie o nome exato para goal.product quando a meta é venda real.


Tools de Datasets

Gerencie datasets customizados: tabelas de dados estruturados para importar dados externos (CSVs, APIs) e usar junto com as outras fontes de dados.

Gerenciamento

list_datasets

Lista todos os datasets do projeto com id, slug, nome, descrição, storage_class, versão atual e resumo do schema.

get_dataset

Retorna detalhes completos de um dataset incluindo schema (colunas, índices) e informações de versão.

dataset_idstringUUID do dataset
create_dataset

Cria um novo dataset com definição de schema. Após criação, chame publish_dataset_version para ativar.

namestringNome do dataset
descriptionstringDescrição
columnsobject[]Definição de colunas: [{ name, kind, nullable?, unique?, default_value? }]. Kind: TEXT, INTEGER, DECIMAL, BOOLEAN, TIMESTAMP, JSON, UUID
update_dataset

Atualiza metadados do dataset (nome e/ou descrição).

dataset_idstringUUID do dataset
namestringNovo nome
descriptionstringNova descrição
delete_dataset

Soft-delete de um dataset. O dataset é desativado mas não removido fisicamente.

dataset_idstringUUID do dataset

Schema e Versionamento

get_dataset_schema

Retorna o schema atual (colunas e índices) de um dataset.

dataset_idstringUUID do dataset
add_dataset_column

Adiciona uma coluna ao dataset. Cria uma versão draft. Chame publish_dataset_version para aplicar.

dataset_idstringUUID do dataset
namestringNome da coluna
kindenumTEXT, INTEGER, DECIMAL, BOOLEAN, TIMESTAMP, JSON
nullablebooleanPermite nulos (padrão: true)
uniquebooleanValores únicos (padrão: false)
default_valuestringValor padrão
update_dataset_column

Atualiza uma coluna com mudanças seguras (ordem, default_value, relaxar constraints). NÃO cria nova versão.

dataset_idstringUUID do dataset
column_namestringNome da coluna
ordernumberNova ordem
default_valuestringNovo valor padrão
remove_dataset_column

Remove uma coluna do dataset. Cria versão draft. Chame publish_dataset_version para aplicar.

CUIDADO: Dados da coluna são permanentemente perdidos após o publish.

dataset_idstringUUID do dataset
column_namestringNome da coluna a remover
publish_dataset_version

Publica mudanças de schema pendentes (adicoes/remocoes de colunas). Aplica todas as mudanças de uma vez.

dataset_idstringUUID do dataset
rollback_dataset_version

Faz rollback do dataset para um número de versão anterior.

dataset_idstringUUID do dataset
versionnumberNúmero da versão para restaurar

Dados

query_dataset_rows

Consulta linhas de um dataset com filtros, ordenação e paginacao baseada em cursor. Retorna linhas, total e metadados do schema.

slugstringSlug do dataset (identificador legivel)
filtersobjectFiltros de consulta
order_bystringCampo para ordenação
order_directionenumasc ou desc
cursorstringCursor para paginacao
limitnumberLimite de linhas (padrão: 50)
upsert_dataset_rows

Insere ou atualiza linhas. Se 'id' existe: UPDATE. Se 'id' não encontrado: INSERT com aquele id. Se 'id' ausente: INSERT com UUID auto-gerado. Max 1000 linhas por chamada.

slugstringSlug do dataset
rowsobject[]Array de objetos com os dados (max 1000)
delete_dataset_rows

Deleta linhas de um dataset pelos seus UUIDs.

slugstringSlug do dataset
row_idsstring[]Array de UUIDs das linhas a deletar
get_dataset_count

Conta linhas de um dataset, opcionalmente com filtros.

slugstringSlug do dataset
filtersobjectFiltros opcionais

Importação CSV

import_csv_to_dataset

Importa um arquivo CSV local para um dataset existente. Le o arquivo do filesystem, faz parse e envia em batches. Use column_mapping para renomear headers do CSV para nomes de colunas do dataset.

dataset_slugstringSlug do dataset de destino
file_pathstringCaminho absoluto do arquivo CSV
column_mappingobjectMapa de renomeacao: { "header_csv": "coluna_dataset" }
delimiterstringDelimitador (padrão: ",")
skip_rowsnumberLinhas para pular no início (padrão: 0)
batch_sizenumberTamanho do batch (padrão: 100)
smart_import_csv

Le um CSV local, infere schema (nomes e tipos de colunas), cria um novo dataset e importa todos os dados automaticamente. Use column_mapping para renomear colunas e column_types para sobrescrever tipos inferidos.

file_pathstringCaminho absoluto do arquivo CSV
namestringNome do dataset a ser criado
descriptionstringDescrição do dataset
column_mappingobjectMapa de renomeacao de colunas
column_typesobjectOverride de tipos: { "coluna": "TEXT"|"INTEGER"|"DECIMAL"|"BOOLEAN"|"TIMESTAMP" }
delimiterstringDelimitador (padrão: ",")
skip_rowsnumberLinhas para pular (padrão: 0)
batch_sizenumberTamanho do batch (padrão: 100)

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.