get_audit_pdf

Qué hace esta herramienta

get_audit_pdf devuelve una URL de descarga firmada para el informe PDF de marca de una auditoría dada. Si todavía no se ha renderizado ningún PDF, encola un render y devuelve un estado queued.

• Toma un audit_id (el mismo valor que devolvió run_audit).
• Devuelve audit_id, pdf_url y status (ready o queued).
• La URL firmada es de vida corta; trátala como descartable y descarga de inmediato.
• Si status: queued, vuelve a llamar a la herramienta unos segundos después, o accede a la URL cuando termine el render.
• La marca blanca (logo, nombre de empresa, tema) sigue el plan del usuario y la configuración del panel.

Por qué importa

El PDF es el entregable que la mayoría de consultores y agencias entregan a sus clientes. Dejar que un agente obtenga una URL firmada significa que una sola llamada MCP puede cerrar un flujo de “auditar e informar” de extremo a extremo que antes requería pestañas del panel.

Flujos concretos:

• Un agente de “informe a cliente” ejecuta run_audit, sondea get_audit, después llama a get_audit_pdf y adjunta la URL firmada a un borrador de correo.
• Un agente de “archivar último trimestre” recorre list_audits, recupera cada PDF y los guarda en Drive o S3 con la URL y el created_at como nombre de archivo.

Cómo usarla

get_audit_pdf es un POST por debajo: la primera llamada dispara un render si la caché está fría. Si el PDF se renderizó hace poco, la URL vuelve de inmediato. Si no, espera 5-15 s de render; sondea la herramienta cada pocos segundos.

Esquema de entrada

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

Ejemplo de esquema de respuesta

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

Cuando el render aún está en curso:

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

Pide:

Obtén el PDF de la auditoría aud_01HZ8X9YP7K3T2N6Q5 desde MetricSpot y dame el enlace de descarga.

Cursor

.cursor/mcp.json:

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

Pide:

Recupera la última auditoría de example.com, espera al PDF y descárgalo a ./reports.

Python (sondear hasta listo, después descargar)

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 crudo)

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()));
}

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
AUDIT_NOT_FOUND (404)	El audit_id no pertenece a esta cuenta	Llama a list_audits para ver ids válidos
FORBIDDEN (403)	La exportación a PDF requiere plan de pago en algunas cuentas	Sube de plan en https://app.metricspot.com/billing
UPSTREAM_FAILED (5xx)	Fallo puntual del servicio de render	Reintenta una vez; se establece retryable: true

Preguntas frecuentes

¿Cuánto tiempo es válida la URL firmada?

De vida corta: minutos, no horas. La URL se firma para descarga puntual y rota en cada llamada. Vuelve a llamar siempre a get_audit_pdf en lugar de cachear la URL en sí; la respuesta es barata cuando el render ya está completo.

¿Puedo personalizar la marca del PDF?

La marca (logo, nombre de empresa, color de acento, pie de página) se configura en el panel en Settings → Branding y se aplica automáticamente a los PDFs renderizados para esa cuenta. La herramienta MCP no acepta overrides por llamada en v1.

¿Qué hay en el PDF que no esté en get_audit?

El PDF es el entregable orientado a personas: portada, resumen ejecutivo, secciones por módulo con capturas y la misma lista de hallazgos con texto de recomendación más largo. get_audit es el JSON estructurado para agentes; el PDF es la versión que entregarías a un cliente.