get_organic_traffic - Docs de MetricSpot

Qué hace esta herramienta

get_organic_traffic devuelve una instantánea de 28 días de tráfico orgánico para una auditoría, extraída de las propiedades vinculadas del usuario en Google Analytics 4 y Google Search Console.

Devuelve connected: false si el usuario aún no ha vinculado Google; el resto de campos quedan vacíos.
Cuando está conectado: sessions_28d (total de sesiones orgánicas), sessions_trend (serie diaria), top_landing_pages (URL + sesiones), top_queries (consulta + clicks + impresiones) y indexed_pages desde GSC.
Cacheado 24 horas en servidor por auditoría, así que las llamadas repetidas son baratas e idempotentes.
Siempre asociado a un audit_id concreto; la ventana de datos es relativa al created_at de esa auditoría.

Por qué importa

Las auditorías de SEO sin datos de tráfico dicen a los agentes qué corregir, pero no qué corregir primero. get_organic_traffic permite que un agente ordene las páginas que fallan por valor orgánico real, para que las recomendaciones aterricen en URLs que de verdad mueven ingresos.

Flujos concretos:

Un agente de “¿por dónde empiezo?” llama a get_audit para los hallazgos y a get_organic_traffic para las sesiones, después redacta una lista de correcciones ordenada por sessions_28d por landing page.
Un agente de gap de consultas lee top_queries (impresiones altas, pocos clicks) y reescribe el título y la meta description de la página correspondiente para subir el CTR.

Cómo usarla

El usuario debe conectar primero Google Analytics 4 y Search Console dentro del panel de MetricSpot. Cuando no está conectado, la herramienta sigue teniendo éxito: devuelve connected: false para que los agentes degraden con elegancia e indiquen al usuario cómo vincular Google.

Esquema de entrada

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

Ejemplo de esquema de respuesta

{
  "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
}

Cuando Google no está vinculado:

{
  "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"

Pide:

Para la auditoría de MetricSpot aud_01HZ8X9YP7K3T2N6Q5, trae la instantánea de tráfico orgánico y dime qué consulta del top-10 tiene el peor CTR.

Cursor

.cursor/mcp.json:

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

Pide:

Combina los hallazgos de la auditoría con get_organic_traffic y lista las páginas que fallan y aportan más sesiones.

Python (ordenar páginas por tráfico)

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 crudo)

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`);
}

Errores comunes

Código	Cuándo	Acción
`UNAUTHORIZED` (401)	Token Bearer ausente o inválido	Emite una clave en `https://app.metricspot.com/settings/api-keys`
`AUDIT_NOT_FOUND` (404)	El `audit_id` no pertenece a esta cuenta	Llama a `list_audits` para ver ids válidos
`FORBIDDEN` (403)	El token carece del scope de Google	Reemite la clave con los scopes por defecto tras vincular Google
`UPSTREAM_FAILED` (5xx)	Caída de la API de GA4 o GSC	Reintenta; la respuesta se cachea 24 h una vez correcta

Preguntas frecuentes

¿Por qué aparece `connected: false` si veo tráfico en GA4?

La conexión vive del lado de MetricSpot: el usuario debe visitar app.metricspot.com/settings/integrations y vincular Google Analytics 4 y Search Console de forma explícita. MetricSpot lee GA4 vía Analytics Data API y GSC vía Search Console API; ambas requieren grants OAuth que el usuario autoriza una vez.

¿Por qué una ventana de 28 días?

Coincide con cómo GSC informa por defecto sus top queries y es corta como para reflejar cambios recientes (post-despliegue, post-lanzamiento) y a la vez suficientemente larga para suavizar la estacionalidad semanal. La ventana no es configurable en v1.

¿Qué frescura tienen los datos?

Los datos de GA4 suelen estar 24-48 horas por detrás del tiempo real, según la ventana de procesamiento de Google. Los datos de GSC llevan 2-3 días de retraso. La respuesta MCP se cachea 24 horas por audit_id en servidor, así que las llamadas repetidas en el mismo día devuelven la misma instantánea.