get_audit_pdf

What this tool does

get_audit_pdf returns a signed download URL for the branded PDF report of a given audit. If no PDF has been rendered yet, it queues a render and returns a queued status.

• Takes an audit_id (the same value run_audit returned).
• Returns audit_id, pdf_url, and status (ready or queued).
• The signed URL is short-lived; treat it as throwaway and fetch immediately.
• If status: queued, call the tool again after a few seconds, or hit the URL once rendering finishes.
• White-label branding (logo, company name, theme) follows the user’s plan and dashboard settings.

Why it matters

The PDF is the deliverable most consultants and agencies hand to clients. Letting an agent grab a signed URL means a single MCP call can finish an end-to-end “audit and report” workflow that previously required a dashboard tab.

Concrete workflows:

• A “client report” agent runs run_audit, polls get_audit, then calls get_audit_pdf and attaches the signed URL to an email draft.
• An “archive last quarter” agent walks list_audits, fetches each PDF, and stores them in Drive or S3 with the URL and created_at as the filename.

How to use it

get_audit_pdf is a POST under the hood: the first call triggers a render if the cache is cold. If the PDF was rendered recently, the URL comes back immediately. Otherwise expect 5-15 s of render time; poll the tool every few seconds.

Input schema

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

Response schema sample

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

When the render is still in progress:

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

Get the PDF for audit aud_01HZ8X9YP7K3T2N6Q5 from MetricSpot and give me the download link.

Cursor

.cursor/mcp.json:

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

Prompt:

Fetch the latest audit for example.com, wait for the PDF, and download it to ./reports.

Python (poll until ready, then 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 (raw HTTP)

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

Common errors

Code	When	Action
UNAUTHORIZED (401)	Missing or invalid Bearer token	Issue a key at https://app.metricspot.com/settings/api-keys
AUDIT_NOT_FOUND (404)	audit_id doesn’t belong to this account	Call list_audits for valid ids
FORBIDDEN (403)	PDF export requires a paid plan on some accounts	Upgrade at https://app.metricspot.com/billing
UPSTREAM_FAILED (5xx)	Render service blip	Retry once; retryable: true is set

Frequently asked questions

How long is the signed URL valid?

Short-lived: minutes, not hours. The URL is signed for one-off download and rotates on each call. Always re-call get_audit_pdf rather than caching the URL itself; the response is cheap when the render is already complete.

Can I customize the PDF branding?

Branding (logo, company name, accent color, footer) is set in the dashboard under Settings → Branding and applied automatically to PDFs rendered for that account. The MCP tool does not accept per-call overrides in v1.

What’s in the PDF that isn’t in get_audit?

The PDF is the human-facing deliverable: cover page, executive summary, per-module sections with screenshots, and the same findings list with longer-form recommendation copy. get_audit is the structured JSON for agents; the PDF is the version you’d hand a client.