get_audit_pdf

Cosa fa questo strumento

get_audit_pdf restituisce un URL firmato di download per il report PDF brandizzato di un dato audit. Se nessun PDF è stato ancora renderizzato, mette in coda un render e restituisce uno status queued.

• Prende un audit_id (lo stesso valore restituito da run_audit).
• Restituisce audit_id, pdf_url e status (ready o queued).
• L’URL firmato è a vita breve; trattalo come usa-e-getta e fai il fetch immediatamente.
• Se status: queued, richiama lo strumento dopo qualche secondo, o accedi all’URL una volta che il rendering termina.
• Il branding white-label (logo, nome azienda, tema) segue il piano e le impostazioni della dashboard dell’utente.

Perché è importante

Il PDF è il deliverable che la maggior parte dei consulenti e delle agenzie consegna ai clienti. Permettere a un agente di prendere un URL firmato significa che una singola chiamata MCP può completare un workflow end-to-end “audit e report” che prima richiedeva un tab della dashboard.

Workflow concreti:

• Un agente “client report” esegue run_audit, fa polling su get_audit, poi chiama get_audit_pdf e allega l’URL firmato a una bozza di email.
• Un agente “archivia ultimo trimestre” itera su list_audits, recupera ogni PDF e li salva su Drive o S3 con l’URL e il created_at come nome file.

Come usarlo

get_audit_pdf è un POST sotto il cofano: la prima chiamata fa partire un render se la cache è fredda. Se il PDF è stato renderizzato di recente, l’URL torna immediatamente. Altrimenti aspettati 5-15 s di tempo di rendering; fai polling sullo strumento ogni pochi secondi.

Schema di input

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

Esempio di schema di risposta

{
  "audit_id": "aud_01HZ8X9YP7K3T2N6Q5",
  "pdf_url": "https://cdn.metricspot.com/reports/aud_01HZ8X9YP7K3T2N6Q5.pdf?signature=...",
  "status": "ready"
}

Quando il render è ancora in corso:

{
  "audit_id": "aud_01HZ8X9YP7K3T2N6Q5",
  "pdf_url": "",
  "status": "queued"
}

Claude Code

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

Prompt:

Recupera il PDF per l’audit aud_01HZ8X9YP7K3T2N6Q5 da MetricSpot e dammi il link di download.

Cursor

.cursor/mcp.json:

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

Prompt:

Recupera l’ultimo audit per example.com, aspetta il PDF e scaricalo in ./reports.

Python (polling fino a ready, poi download)

import httpx, time, json

HEADERS = {
    "content-type": "application/json",
    "accept": "application/json, text/event-stream",
    "authorization": "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx",
}

def call(name, args):
    r = httpx.post("https://mcp.metricspot.com/mcp", 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"])

for _ in range(10):
    pdf = call("get_audit_pdf", {"audit_id": "aud_01HZ8X9YP7K3T2N6Q5"})
    if pdf["status"] == "ready":
        break
    time.sleep(3)

with httpx.stream("GET", pdf["pdf_url"]) as r:
    with open("report.pdf", "wb") as f:
        for chunk in r.iter_bytes():
            f.write(chunk)

Node / TypeScript (HTTP grezzo)

import { writeFile } from "node:fs/promises";

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_audit_pdf",
      arguments: { audit_id: "aud_01HZ8X9YP7K3T2N6Q5" },
    },
  }),
});
const pdf = JSON.parse((await res.json()).result.content[0].text);
if (pdf.status === "ready") {
  const file = await fetch(pdf.pdf_url);
  await writeFile("report.pdf", Buffer.from(await file.arrayBuffer()));
}

Errori comuni

Codice	Quando	Azione
UNAUTHORIZED (401)	Bearer token mancante o non valido	Genera una chiave su https://app.metricspot.com/settings/api-keys
AUDIT_NOT_FOUND (404)	audit_id non appartiene a questo account	Chiama list_audits per id validi
FORBIDDEN (403)	L’export PDF richiede un piano a pagamento su alcuni account	Aggiorna su https://app.metricspot.com/billing
UPSTREAM_FAILED (5xx)	Singhiozzo del servizio di rendering	Riprova una volta; retryable: true è impostato

Domande frequenti

Quanto è valido l’URL firmato?

A vita breve: minuti, non ore. L’URL è firmato per un download one-off e ruota a ogni chiamata. Richiama sempre get_audit_pdf invece di cachare l’URL stesso; la risposta è economica quando il render è già completo.

Posso personalizzare il branding del PDF?

Il branding (logo, nome azienda, colore d’accento, footer) è impostato nella dashboard sotto Settings → Branding e applicato automaticamente ai PDF renderizzati per quell’account. Lo strumento MCP non accetta override per-chiamata in v1.

Cosa c’è nel PDF che non c’è in get_audit?

Il PDF è il deliverable umano: copertina, riassunto esecutivo, sezioni per modulo con screenshot e la stessa lista di finding con un testo di raccomandazione più esteso. get_audit è il JSON strutturato per gli agenti; il PDF è la versione che daresti a un cliente.