run_audit

Qué hace esta herramienta

run_audit encola una auditoría completa de SEO y legibilidad para IA y devuelve de inmediato el sobre de auditoría. Es la versión autenticada y completa de run_audit_anonymous.

• Encola la auditoría de forma asíncrona y devuelve status: queued más un audit_id real en 1-2 segundos.
• Obtiene Core Web Vitals (LCP, CLS, INP) desde Google PageSpeed Insights como parte de la ejecución.
• Si el usuario ha vinculado Google Analytics 4 y Search Console, también obtiene señales de tráfico orgánico, que se exponen aparte mediante get_organic_traffic.
• Cuenta contra la asignación del plan del usuario (Free 10/mes, Starter 50/mes, Pro ilimitado) y respeta cooldowns por dominio.
• Devuelve la misma forma McpAuditResponse que get_audit. Los hallazgos estarán vacíos hasta que la auditoría pase a complete.

Por qué importa

run_audit es la herramienta adecuada siempre que necesites una auditoría persistente que puedas recuperar después, un PDF, datos de tráfico orgánico o Core Web Vitals. Las auditorías anónimas cubren ~90 comprobaciones pero omiten PSI; esta herramienta cubre todo.

Flujos concretos:

• Un bot de auditoría en PR llama a run_audit cuando se publica un despliegue de vista previa, captura el audit_id, sondea get_audit cada 5 s durante hasta 60 s y publica un comentario con el delta frente a la última auditoría de la misma URL.
• Un agente cron semanal itera por las landing pages más visitadas del usuario y encola un run_audit nuevo para cada una; después envía un resumen desde list_audits.

Cómo usarla

La herramienta es asíncrona por diseño. Trata la respuesta inmediata como un acuse de recibo y después sondea get_audit con el audit_id devuelto cada pocos segundos. El tiempo típico de extremo a extremo es 10-30 s; permite hasta 90 s para objetivos lentos.

Esquema de entrada

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

Ejemplo de esquema de respuesta

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

Cuando la auditoría completa, get_audit devuelve la misma forma con status: "complete", un total_score poblado, module_scores y el array findings.

Claude Code

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

Pide:

Ejecuta una auditoría completa de MetricSpot en https://example.com, sondea hasta que complete y resume los hallazgos críticos y mayores que fallen.

Cursor

.cursor/mcp.json:

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

Pide:

Encola una auditoría para esta página, espera a que complete y dime mis puntuaciones de Core Web Vitals.

Python (ejecutar + sondear)

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

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
QUOTA_EXCEEDED (402)	Asignación mensual del plan alcanzada	Sube de plan en https://app.metricspot.com/billing
RATE_LIMITED (429)	Cooldown por dominio alcanzado	Espera la ventana indicada antes de volver a encolar el mismo dominio
INVALID_URL (400)	URL inválida, host no público, o más de 2000 caracteres	Pasa una URL absoluta con https://
UPSTREAM_FAILED (5xx)	Fallo puntual en PSI o el crawler	Reintenta una vez con backoff

Preguntas frecuentes

¿Cuánto tarda la auditoría en estar complete?

10-30 segundos en sitios típicos. Objetivos lentos, páginas con mucho JS o sitios con grandes cantidades de datos estructurados pueden tardar hasta 90 segundos. Sondea get_audit cada 3-5 segundos; la auditoría está totalmente calculada cuando status pasa a complete.

¿run_audit consume una auditoría aunque falle?

Una auditoría failed no consume asignación del plan. La cuota solo decrementa cuando la ejecución termina con éxito y los hallazgos quedan almacenados. Los fallos por rate-limit de PSI se reintentan internamente antes de exponerse.

¿Puedo obtener el PDF y el tráfico orgánico en la misma llamada?

No, son herramientas separadas por diseño. Cuando run_audit complete, llama a get_audit_pdf para la URL firmada del PDF y a get_organic_traffic para la instantánea de GA4 + GSC. Ambas referencian el mismo audit_id.