run_audit

Ce que fait cet outil

run_audit met en file d’attente un audit SEO et de lisibilité IA complet et renvoie immédiatement l’enveloppe de l’audit. C’est la version authentifiée et complète de run_audit_anonymous.

• Met en file d’attente l’audit en asynchrone et renvoie status: queued plus un vrai audit_id en 1-2 secondes.
• Récupère les Core Web Vitals (LCP, CLS, INP) depuis Google PageSpeed Insights dans le cadre de l’exécution.
• Si l’utilisateur a lié Google Analytics 4 et Search Console, récupère aussi les signaux de trafic organique, exposés séparément via get_organic_traffic.
• Décompté du quota du plan de l’utilisateur (Free 10/mois, Starter 50/mois, Pro illimité) et respecte les cooldowns par domaine.
• Renvoie la même forme McpAuditResponse que get_audit. Les constats restent vides jusqu’à ce que l’audit passe à complete.

Pourquoi c’est important

run_audit est le bon outil dès que vous avez besoin d’un audit persistant récupérable plus tard, d’un PDF, de données de trafic organique ou de Core Web Vitals. Les audits anonymes couvrent ~90 contrôles mais sautent PSI ; cet outil couvre tout.

Workflows concrets :

• Un bot d’audit sur PR appelle run_audit quand un déploiement preview est publié, capture l’audit_id, interroge get_audit toutes les 5 s pendant jusqu’à 60 s, puis poste un commentaire d’écart par rapport au dernier audit de la même URL.
• Un agent cron hebdomadaire parcourt les landing pages les plus visitées de l’utilisateur et met en file d’attente un run_audit frais pour chacune, puis envoie un récapitulatif à partir de list_audits.

Comment l’utiliser

L’outil est asynchrone par conception. Traitez la réponse immédiate comme un accusé de réception, puis interrogez get_audit avec l’audit_id renvoyé toutes les quelques secondes. La complétion typique de bout en bout est de 10-30 s ; comptez jusqu’à 90 s pour les cibles lentes.

Schéma d’entrée

{
  "type": "object",
  "properties": {
    "url": { "type": "string", "format": "uri", "maxLength": 2000 }
  },
  "required": ["url"]
}

Exemple de schéma de réponse

{
  "audit_id": "aud_01HZ8X9YP7K3T2N6Q5",
  "url": "https://example.com",
  "status": "queued",
  "total_score": null,
  "module_scores": {},
  "findings": [],
  "report_url": "https://app.metricspot.com/audits/aud_01HZ8X9YP7K3T2N6Q5",
  "created_at": "2026-05-13T10:18:04.000Z"
}

Lorsque l’audit se termine, la même forme est renvoyée par get_audit avec status: "complete", un total_score rempli, module_scores et le tableau findings.

Claude Code

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

Demandez :

Lance un audit MetricSpot complet sur https://example.com, interroge jusqu’à la fin et résume les constats critiques et majeurs en échec.

Cursor

.cursor/mcp.json :

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

Demandez :

Mets en file d’attente un audit pour cette page, attends la complétion et donne-moi mes scores Core Web Vitals.

Python (lancer + interroger)

import httpx, time, json

URL = "https://mcp.metricspot.com/mcp"
HEADERS = {
    "content-type": "application/json",
    "accept": "application/json, text/event-stream",
    "authorization": "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx",
}

def call(name, args):
    r = httpx.post(URL, headers=HEADERS, json={
        "jsonrpc": "2.0", "id": 1, "method": "tools/call",
        "params": {"name": name, "arguments": args},
    }, timeout=60.0)
    return json.loads(r.json()["result"]["content"][0]["text"])

queued = call("run_audit", {"url": "https://example.com"})
audit_id = queued["audit_id"]

for _ in range(30):
    time.sleep(3)
    result = call("get_audit", {"audit_id": audit_id})
    if result["status"] in ("complete", "failed"):
        break

print(result["total_score"], len(result["findings"]))

Node / TypeScript (avec @modelcontextprotocol/sdk)

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://mcp.metricspot.com/mcp"),
  {
    requestInit: {
      headers: { authorization: "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx" },
    },
  },
);
const client = new Client({ name: "audit-on-pr", version: "1.0.0" });
await client.connect(transport);

const queued = await client.callTool({
  name: "run_audit",
  arguments: { url: "https://example.com" },
});
const auditId = JSON.parse(queued.content[0].text as string).audit_id;
console.log("queued", auditId);

Erreurs courantes

Code	Quand	Action
UNAUTHORIZED (401)	Jeton Bearer manquant ou invalide	Émettez une clé sur https://app.metricspot.com/settings/api-keys
QUOTA_EXCEEDED (402)	Quota mensuel du plan atteint	Montez en plan sur https://app.metricspot.com/billing
RATE_LIMITED (429)	Cooldown par domaine atteint	Attendez la fenêtre indiquée avant de remettre le même domaine en file
INVALID_URL (400)	URL invalide, hôte non public, ou > 2000 caractères	Passez une URL absolue en https://
UPSTREAM_FAILED (5xx)	Hoquet en amont PSI ou crawler	Réessayez une fois avec backoff

Questions fréquentes

Combien de temps avant que l’audit soit complete ?

10-30 secondes pour les sites typiques. Les cibles lentes, les pages chargées en JS, ou les sites avec beaucoup de données structurées peuvent prendre jusqu’à 90 secondes. Interrogez get_audit toutes les 3-5 secondes ; l’audit est entièrement calculé une fois que status bascule sur complete.

run_audit consomme-t-il un audit même en cas d’échec ?

Un audit failed ne consomme pas le quota du plan. Le quota n’est décrémenté qu’une fois l’exécution terminée avec succès et les constats stockés. Les échecs de rate-limit PSI sont réessayés en interne avant d’être remontés.

Puis-je obtenir le PDF et le trafic organique dans le même appel ?

Non, ce sont des outils séparés par conception. Une fois run_audit terminé, appelez get_audit_pdf pour l’URL PDF signée et get_organic_traffic pour l’instantané GA4 + GSC. Les deux référencent le même audit_id.