run_audit

O que esta ferramenta faz

run_audit põe em fila uma auditoria completa de SEO e legibilidade para IA e devolve imediatamente o envelope da auditoria. É a versão autenticada e completa de run_audit_anonymous.

• Põe a auditoria em fila de forma assíncrona e devolve status: queued mais um audit_id real em 1-2 segundos.
• Vai buscar Core Web Vitals (LCP, CLS, INP) ao Google PageSpeed Insights como parte da execução.
• Se o utilizador tiver ligado Google Analytics 4 e Search Console, também vai buscar sinais de tráfego orgânico, expostos separadamente via get_organic_traffic.
• Conta para a quota do plano do utilizador (Free 10/mês, Starter 50/mês, Pro ilimitado) e respeita cooldowns por domínio.
• Devolve a mesma forma McpAuditResponse que get_audit. As descobertas ficam vazias até a auditoria transitar para complete.

Por que importa

run_audit é a ferramenta certa sempre que precisas de uma auditoria persistente que possas ir buscar mais tarde, um PDF, dados de tráfego orgânico ou Core Web Vitals. As auditorias anónimas cobrem cerca de 90 verificações mas saltam o PSI; esta ferramenta cobre tudo.

Fluxos concretos:

• Um bot de auditoria-no-PR chama run_audit quando um deploy de preview é publicado, captura o audit_id, faz polling a get_audit de 5 em 5 s até 60 s, e publica um comentário de delta face à última auditoria no mesmo URL.
• Um agente cron semanal itera as landing pages mais visitadas do utilizador e põe em fila uma nova run_audit para cada uma, depois envia um resumo a partir de list_audits.

Como usá-la

A ferramenta é assíncrona por design. Trata a resposta imediata como um reconhecimento, depois faz polling a get_audit com o audit_id devolvido de poucos em poucos segundos. A conclusão típica ponta-a-ponta é de 10-30 s; permite até 90 s para alvos lentos.

Schema de entrada

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

Amostra do schema 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"
}

Quando a auditoria termina, a mesma forma é devolvida por get_audit com status: "complete", um total_score preenchido, module_scores e o array findings.

Claude Code

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

Pede:

Corre uma auditoria MetricSpot completa em https://example.com, faz polling até estar pronta, e resume as descobertas críticas e majores que falharam.

Cursor

.cursor/mcp.json:

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

Pede:

Põe em fila uma auditoria para esta página, espera pela conclusão, e diz-me as minhas pontuações de Core Web Vitals.

Python (correr + polling)

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

Erros comuns

Código	Quando	Ação
UNAUTHORIZED (401)	Token Bearer em falta ou inválido	Emite uma chave em https://app.metricspot.com/settings/api-keys
QUOTA_EXCEEDED (402)	Quota mensal do plano atingida	Faz upgrade em https://app.metricspot.com/billing
RATE_LIMITED (429)	Cooldown por domínio atingido	Espera a janela indicada antes de pôr em fila o mesmo domínio
INVALID_URL (400)	URL inválido, host não público, ou > 2000 caracteres	Passa um URL absoluto https://
UPSTREAM_FAILED (5xx)	Falha pontual no upstream PSI ou crawler	Tenta uma vez com backoff

Perguntas frequentes

Quanto tempo até a auditoria ficar complete?

10-30 segundos para sites típicos. Alvos lentos, páginas com muito JS, ou sites com grandes quantidades de dados estruturados podem demorar até 90 segundos. Faz polling a get_audit de 3 em 3 ou 5 em 5 segundos; a auditoria está totalmente computada quando o status muda para complete.

run_audit consome uma auditoria mesmo que falhe?

Uma auditoria failed não consome a quota do plano. A quota só decrementa quando a execução termina com sucesso e as descobertas ficam guardadas. As falhas de rate-limit do PSI são tentadas novamente internamente antes de serem expostas.

Posso obter o PDF e o tráfego orgânico na mesma chamada?

Não, são ferramentas separadas por design. Depois de run_audit terminar, chama get_audit_pdf para o URL assinado do PDF e get_organic_traffic para a fotografia GA4 + GSC. Ambas referenciam o mesmo audit_id.