GA4 via MCP: relatório sob demanda e administração da propriedade sem abrir a interface

A interface do GA4 é famosa por transformar perguntas simples em expedições. “Quantos leads vieram de tráfego pago no mês passado, por landing page?” deveria ser trivial e envolve montar exploração, arrastar dimensão, escolher métrica e torcer para a amostragem não atrapalhar.

Via MCP, é uma frase. Este artigo mostra como o bloco GA4 funciona e onde ele derrapa.

As tools de leitura

analytics_list_properties

Lista as propriedades acessíveis pela conexão. É o primeiro passo sempre, porque o resto exige o propertyId numérico — e ninguém decora isso para oito clientes.

analytics_report

O motor. Recebe propertyId, dimensions, metrics, startDate, endDate e um limit opcional.

As datas aceitam formato absoluto (2026-07-01) ou relativo (30daysAgo, today). O relativo é mais prático para rotina recorrente; o absoluto é obrigatório quando você precisa de comparação estável entre execuções.

Exemplo de combinação que resolve a pergunta lá do começo:

dimensions: ["landingPage", "sessionDefaultChannelGroup"]
metrics: ["sessions", "keyEvents", "engagedSessions"]
startDate: "30daysAgo"
endDate: "today"

analytics_realtime

Usuários ativos agora, com dimensões opcionais como country e deviceCategory. Uso principal: validar se uma tag nova está disparando logo depois de subir. Para análise, tem pouco valor.

A armadilha das combinações inválidas

Este é o ponto que mais gera frustração para quem usa GA4 por API pela primeira vez.

Nem toda dimensão combina com toda métrica. O GA4 organiza dados em escopos — evento, sessão, usuário, item. Cruzar escopos incompatíveis gera erro ou, pior, resultado silenciosamente errado.

Exemplos clássicos:

• eventName (escopo de evento) com sessions (escopo de sessão) — a leitura fica ambígua
• Dimensões de item de e-commerce com métricas de sessão
• landingPage com métricas que não são de sessão

Um modelo de linguagem escreve essas combinações razoavelmente bem, mas erra em casos menos comuns. Quando a API rejeita, o erro vem descritivo — é só pedir correção. O caso perigoso é quando não rejeita e o número sai estranho. Desconfie de qualquer resultado que contrarie sua intuição sobre a conta.

Outra pegadinha de nomenclatura: a métrica mudou de nome. O que era conversions hoje é keyEvents. Modelos treinados em documentação antiga usam o nome velho e a chamada falha. Vale saber para corrigir rápido.

Amostragem e defasagem

Duas características do GA4 que afetam confiança no dado e que a API não avisa em voz alta:

Amostragem. Consultas complexas em períodos longos com muito volume podem vir amostradas. O número é estimativa, não contagem. Para propriedade de porte médio raramente acontece, mas vale saber que existe antes de brigar com o cliente sobre uma diferença de 3%.

Defasagem de processamento. Dado do GA4 não é definitivo em tempo real. Consultar “ontem” às 8h da manhã costuma devolver número incompleto, que sobe ao longo do dia. Implementações mais cuidadosas aplicam uma defasagem automática — ignoram os últimos dias justamente para não reportar dado que ainda vai mudar.

Se você monta rotina de relatório recorrente, considere isso. Relatório de segunda-feira sobre a semana que fechou domingo vai subestimar o domingo.

As tools de administração

É aqui que o MCP passa de “leitor de relatório” para ferramenta de trabalho de verdade. A API de administração do GA4 permite configurar a propriedade, não só consultá-la.

Key events

• ga4_list_key_events — lista os eventos marcados como conversão
• ga4_create_key_event — marca um evento, com countingMethod ONCE_PER_EVENT ou ONCE_PER_SESSION
• ga4_delete_key_event — remove, pelo resourceName completo

O caso de uso óbvio é setup de cliente novo. O menos óbvio, e mais valioso, é auditoria de carteira: rodar ga4_list_key_events em todas as propriedades e comparar. Cliente com zero key events é cliente sem mensuração. Cliente com quinze é cliente cujo Smart Bidding está otimizando para ruído.

Detalhei a lógica de escolha de conversão primária no artigo sobre ligar Google Ads e GA4 sem quebrar o rastreamento.

Dimensões personalizadas

• ga4_list_custom_dimensions — lista as existentes
• ga4_create_custom_dimension — cria, com displayName, parameterName e scope (EVENT ou USER)

Duas regras não negociáveis. Dimensão personalizada não é retroativa — ela só coleta a partir do momento em que é criada. E existe limite por propriedade, então não registre tudo por precaução.

A consequência prática: no setup de cliente novo, registre as dimensões antes de começar a rodar tráfego. Um mês de dado perdido não volta.

O que a API não faz

Vale ser claro sobre o limite, porque promessa exagerada aqui gera frustração:

• Não cria propriedade nem stream de dados do zero pela via administrativa comum
• Não configura GTM — isso é outra API, outro produto
• Não cria públicos-alvo
• Não altera configuração de atribuição ou de retenção de dados
• Não substitui a validação visual no DebugView quando você está caçando tag quebrada

O MCP cobre o ciclo de consultar, marcar conversão e registrar dimensão. O resto continua na interface — o que é razoável, já que são operações que você faz uma vez por cliente.

O ganho real: auditoria em escala

Se eu tivesse que apontar um único uso que justifica conectar GA4 via MCP, seria este.

Uma rotina mensal que, em carteira de oito clientes, ninguém executa na mão:

1. Listar todas as propriedades acessíveis
2. Para cada uma, listar os key events
3. Rodar um relatório de contagem por evento nos últimos 30 dias
4. Comparar com o período anterior
5. Sinalizar: key event que zerou, evento novo que apareceu, propriedade sem key event nenhum

Key event que zerou é rastreamento quebrado. Site atualizou, plugin trocou, desenvolvedor mexeu no formulário. O sintoma no Ads chega semanas depois como queda de conversão sem queda de tráfego, e aí você já perdeu otimização.

Essa rotina em cinco minutos, contra uma tarde inteira de cliques, é o argumento inteiro a favor do MCP. É o mesmo raciocínio que aplico em gestão de múltiplos sites via MCP: o valor não está numa tarefa, está na repetição.

No próximo artigo eu mostro como jogar esses relatórios direto numa planilha do Google Sheets, fechando o pipeline de leitura até entrega ao cliente.