get_organic_traffic - Docs do MetricSpot

O que esta ferramenta faz

get_organic_traffic devolve uma fotografia de 28 dias de tráfego orgânico para uma auditoria, vinda das propriedades Google Analytics 4 e Google Search Console ligadas pelo utilizador.

Devolve connected: false se o utilizador ainda não ligou a Google, os restantes campos ficam então vazios.
Quando ligado: sessions_28d (total de sessões orgânicas), sessions_trend (série diária), top_landing_pages (URL + sessões), top_queries (query + clicks + impressions), e indexed_pages do GSC.
Cacheado 24 horas no servidor por auditoria, por isso chamadas repetidas são baratas e idempotentes.
Sempre ligado a um audit_id específico; a janela de dados é relativa ao created_at dessa auditoria.

Por que importa

Auditorias SEO sem dados de tráfego dizem aos agentes o que corrigir, mas não o que corrigir primeiro. get_organic_traffic permite a um agente ordenar páginas com falhas por valor orgânico real, para que as recomendações caiam sobre URLs que realmente movem receita.

Fluxos concretos:

Um agente “por onde começar?” chama get_audit para descobertas e get_organic_traffic para sessões, depois rascunha uma lista de correções ordenada por sessions_28d por landing page.
Um agente de gap de queries lê top_queries (alta exposição, poucos cliques) e reescreve o título e a meta description da página correspondente para subir o CTR.

Como usá-la

O utilizador tem de ligar Google Analytics 4 e Search Console dentro do dashboard MetricSpot primeiro. Quando não está ligado, a ferramenta continua a ter sucesso, devolve connected: false para que os agentes possam degradar graciosamente e dizer ao utilizador como ligar a Google.

Schema de entrada

{
  "type": "object",
  "properties": {
    "audit_id": { "type": "string", "minLength": 1 }
  },
  "required": ["audit_id"]
}

Amostra do schema de resposta

{
  "audit_id": "aud_01HZ8X9YP7K3T2N6Q5",
  "connected": true,
  "sessions_28d": 14328,
  "sessions_trend": [
    { "date": "2026-04-15", "sessions": 482 },
    { "date": "2026-04-16", "sessions": 511 },
    { "date": "2026-04-17", "sessions": 539 }
  ],
  "top_landing_pages": [
    { "url": "https://example.com/", "sessions": 5104 },
    { "url": "https://example.com/pricing", "sessions": 2871 },
    { "url": "https://example.com/blog/launch", "sessions": 1942 }
  ],
  "top_queries": [
    { "query": "example pricing", "clicks": 612, "impressions": 8412 },
    { "query": "example alternative", "clicks": 387, "impressions": 5101 }
  ],
  "indexed_pages": 184
}

Quando a Google não está ligada:

{
  "audit_id": "aud_01HZ8X9YP7K3T2N6Q5",
  "connected": false,
  "sessions_28d": null,
  "indexed_pages": null
}

Claude Code

claude mcp add --transport http metricspot https://mcp.metricspot.com/mcp \
  --header "Authorization: Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Pede:

Para a auditoria MetricSpot aud_01HZ8X9YP7K3T2N6Q5, vai buscar a fotografia de tráfego orgânico e diz-me que query do top 10 tem o pior CTR.

Cursor

.cursor/mcp.json:

{
  "mcpServers": {
    "metricspot": {
      "url": "https://mcp.metricspot.com/mcp",
      "headers": {
        "Authorization": "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Pede:

Combina as descobertas da auditoria com get_organic_traffic e lista as páginas que falham e que trazem mais sessões.

Python (ordenar páginas por tráfego)

import httpx, json

HEADERS = {
    "content-type": "application/json",
    "accept": "application/json, text/event-stream",
    "authorization": "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx",
}

r = httpx.post("https://mcp.metricspot.com/mcp", headers=HEADERS, json={
    "jsonrpc": "2.0", "id": 1, "method": "tools/call",
    "params": {
        "name": "get_organic_traffic",
        "arguments": {"audit_id": "aud_01HZ8X9YP7K3T2N6Q5"},
    },
}, timeout=30.0)

snap = json.loads(r.json()["result"]["content"][0]["text"])
if not snap["connected"]:
    print("Connect GA4 + GSC at app.metricspot.com/settings/integrations")
else:
    for q in snap.get("top_queries", [])[:5]:
        ctr = q["clicks"] / q["impressions"] if q["impressions"] else 0
        print(f"{q['query']}: CTR {ctr:.1%} ({q['clicks']} / {q['impressions']})")

Node / TypeScript (HTTP direto)

const res = await fetch("https://mcp.metricspot.com/mcp", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    accept: "application/json, text/event-stream",
    authorization: "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx",
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "tools/call",
    params: {
      name: "get_organic_traffic",
      arguments: { audit_id: "aud_01HZ8X9YP7K3T2N6Q5" },
    },
  }),
});
const snap = JSON.parse((await res.json()).result.content[0].text);
if (snap.connected) {
  console.log(`${snap.sessions_28d} sessions in last 28d`);
}

Erros comuns

Código	Quando	Ação
`UNAUTHORIZED` (401)	Token Bearer em falta ou inválido	Emite uma chave em `https://app.metricspot.com/settings/api-keys`
`AUDIT_NOT_FOUND` (404)	`audit_id` não pertence a esta conta	Chama `list_audits` para ids válidos
`FORBIDDEN` (403)	Token sem o scope Google	Reemite a chave com os scopes padrão depois de ligar a Google
`UPSTREAM_FAILED` (5xx)	Falha de API GA4 ou GSC	Tenta de novo; a resposta é cacheada 24h quando bem-sucedida

Perguntas frequentes

Porque é que `connected: false` mesmo eu vendo tráfego no GA4?

A ligação vive do lado do MetricSpot: o utilizador tem de visitar app.metricspot.com/settings/integrations e ligar Google Analytics 4 e Search Console explicitamente. O MetricSpot lê o GA4 via Analytics Data API e o GSC via Search Console API; ambos exigem permissões OAuth que o utilizador autoriza uma vez.

Porquê uma janela de 28 dias?

Combina com a forma como o GSC reporta as suas top queries por defeito e é curta o suficiente para refletir mudanças recentes (pós-deploy, pós-lançamento) mas suficientemente longa para suavizar a sazonalidade semanal. A janela não é configurável na v1.

Quão recentes são os dados?

Os dados GA4 estão tipicamente 24-48 horas atrás do tempo real, conforme a janela de processamento da Google. Os dados GSC têm um atraso de 2-3 dias. A resposta MCP é cacheada 24 horas por audit_id no servidor, por isso chamadas repetidas no mesmo dia devolvem a mesma fotografia.