run_audit

Què fa aquesta eina

run_audit encua una auditoria SEO i d’AI-readability completa i retorna immediatament amb el sobre d’auditoria. És la versió autenticada i completa de run_audit_anonymous.

• Encua l’auditoria de forma asíncrona i retorna status: queued més un audit_id real en 1-2 segons.
• Obté els Core Web Vitals (LCP, CLS, INP) de Google PageSpeed Insights com a part de l’execució.
• Si l’usuari ha vinculat Google Analytics 4 i Search Console, també recull senyals de tràfic orgànic: exposats per separat via get_organic_traffic.
• Compta contra l’allocació del pla de l’usuari (Free 10/mes, Starter 50/mes, Pro il·limitat) i respecta els cooldowns per domini.
• Retorna la mateixa forma McpAuditResponse que get_audit. Els findings estaran buits fins que l’auditoria passi a complete.

Per què importa

run_audit és l’eina adequada sempre que necessitis una auditoria persistent que puguis recuperar després, un PDF, dades de tràfic orgànic o Core Web Vitals. Les auditories anònimes cobreixen ~90 comprovacions però salten PSI; aquesta eina ho cobreix tot.

Fluxos concrets:

• Un bot d’auditoria a les PR crida run_audit quan es desplega una preview, captura l’audit_id, fa poll a get_audit cada 5 s fins a 60 s, i publica un comentari amb la diferència respecte a la darrera auditoria de la mateixa URL.
• Un agent cron setmanal recorre les landing pages més visitades de l’usuari i encua un run_audit nou per a cadascuna, i després envia un resum des de list_audits.

Com utilitzar-la

L’eina és asíncrona per disseny. Tracta la resposta immediata com una confirmació, i després fes poll a get_audit amb l’audit_id retornat cada pocs segons. El temps típic de finalització és de 10-30 s; preveu fins a 90 s per a objectius lents.

Esquema d’entrada

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

Mostra de l’esquema de resposta

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

Quan l’auditoria acaba, get_audit retorna la mateixa forma amb status: "complete", un total_score omplert, module_scores i l’array findings.

Claude Code

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

Prompt:

Run a full MetricSpot audit on https://example.com, poll until complete, and summarize the failing critical and major findings.

Cursor

.cursor/mcp.json:

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

Prompt:

Queue an audit for this page, wait for completion, and tell me my Core Web Vitals scores.

Python (executar + poll)

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 (amb @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);

Errors habituals

Codi	Quan	Acció
UNAUTHORIZED (401)	Token Bearer absent o invàlid	Emet una clau a https://app.metricspot.com/settings/api-keys
QUOTA_EXCEEDED (402)	Allocació mensual del pla assolida	Actualitza a https://app.metricspot.com/billing
RATE_LIMITED (429)	Cooldown per domini assolit	Espera la finestra indicada abans de reencuar el mateix domini
INVALID_URL (400)	URL incorrecta, host no públic, o > 2000 caràcters	Passa una URL absoluta https://
UPSTREAM_FAILED (5xx)	Falla puntual de PSI o del rastrejador	Reintenta un cop amb backoff

Preguntes freqüents

Quant fins que l’auditoria estigui complete?

10-30 segons per a llocs típics. Objectius lents, pàgines amb molt JS o llocs amb grans quantitats de dades estructurades poden trigar fins a 90 segons. Fes poll a get_audit cada 3-5 segons; l’auditoria està totalment calculada quan status passa a complete.

run_audit consumeix una auditoria si falla?

Una auditoria amb estat failed no consumeix allocació de pla. La quota només es decrementa quan l’execució acaba correctament i els findings es desen. Els errors de rate-limit de PSI es reintenten internament abans de sortir cap a fora.

Puc obtenir el PDF i el tràfic orgànic a la mateixa crida?

No, són eines separades per disseny. Després que run_audit acabi, crida get_audit_pdf per a la URL del PDF signada i get_organic_traffic per a la instantània GA4 + GSC. Tots dos referencien el mateix audit_id.