get_organic_traffic - Docs MetricSpot

Ce que fait cet outil

get_organic_traffic renvoie un instantané sur 28 jours du trafic organique d’un audit, tiré des propriétés Google Analytics 4 et Google Search Console liées par l’utilisateur.

Renvoie connected: false si l’utilisateur n’a pas encore lié Google, le reste des champs étant alors vides.
Lorsque connecté : sessions_28d (total des sessions organiques), sessions_trend (série journalière), top_landing_pages (URL + sessions), top_queries (requête + clics + impressions) et indexed_pages depuis GSC.
Mis en cache 24 heures côté serveur par audit, les appels répétés sont donc peu coûteux et idempotents.
Toujours rattaché à un audit_id précis ; la fenêtre de données est relative au created_at de cet audit.

Pourquoi c’est important

Les audits SEO sans données de trafic disent aux agents quoi corriger, mais pas par quoi commencer. get_organic_traffic permet à un agent de classer les pages en échec selon leur valeur organique réelle, pour que les recommandations atterrissent sur les URL qui font vraiment bouger le chiffre d’affaires.

Workflows concrets :

Un agent “par où je commence ?” appelle get_audit pour les constats et get_organic_traffic pour les sessions, puis rédige une liste de corrections ordonnée par sessions_28d par landing page.
Un agent “écart de requêtes” lit top_queries (impressions élevées, clics faibles) et réécrit le title et la meta description de la page correspondante pour augmenter le CTR.

Comment l’utiliser

L’utilisateur doit d’abord connecter Google Analytics 4 et Search Console depuis le tableau de bord MetricSpot. Lorsque non connecté, l’outil réussit quand même : il renvoie connected: false pour que les agents puissent dégrader gracieusement et indiquer à l’utilisateur comment lier Google.

Schéma d’entrée

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

Exemple de schéma de réponse

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

Quand Google n’est pas lié :

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

Demandez :

Pour l’audit MetricSpot aud_01HZ8X9YP7K3T2N6Q5, récupère l’instantané de trafic organique et dis-moi quelle requête du top 10 a le pire CTR.

Cursor

.cursor/mcp.json :

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

Demandez :

Combine les constats d’audit avec get_organic_traffic et liste les pages en échec qui apportent le plus de sessions.

Python (classer les pages par trafic)

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

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

Erreurs courantes

Code	Quand	Action
`UNAUTHORIZED` (401)	Jeton Bearer manquant ou invalide	Émettez une clé sur `https://app.metricspot.com/settings/api-keys`
`AUDIT_NOT_FOUND` (404)	`audit_id` n’appartient pas à ce compte	Appelez `list_audits` pour des identifiants valides
`FORBIDDEN` (403)	Le jeton n’a pas le scope Google	Réémettez la clé avec les scopes par défaut après avoir lié Google
`UPSTREAM_FAILED` (5xx)	Panne de l’API GA4 ou GSC	Réessayez ; la réponse est mise en cache 24h une fois réussie

Questions fréquentes

Pourquoi `connected: false` alors que je vois du trafic dans GA4 ?

La connexion vit côté MetricSpot : l’utilisateur doit se rendre sur app.metricspot.com/settings/integrations et lier explicitement Google Analytics 4 et Search Console. MetricSpot lit GA4 via l’Analytics Data API et GSC via la Search Console API ; les deux exigent des autorisations OAuth que l’utilisateur accorde une fois.

Pourquoi une fenêtre de 28 jours ?

Elle correspond à la façon dont GSC remonte ses requêtes par défaut, et est assez courte pour refléter les changements récents (post-déploiement, post-lancement) tout en étant assez longue pour lisser la saisonnalité hebdomadaire. La fenêtre n’est pas configurable en v1.

À quel point les données sont-elles fraîches ?

Les données GA4 ont typiquement 24-48 heures de retard sur le temps réel, selon la fenêtre de traitement de Google. Les données GSC ont 2-3 jours de retard. La réponse MCP est mise en cache 24 heures par audit_id côté serveur, donc les appels répétés dans la même journée renvoient le même instantané.