# PDF Reports

> Render a branded PDF report for a mortgage, loan, 401(k), education or credit card scenario with the generate_report tool: what you need, how to call it, download the PDF, and add your branding.

**URL**: https://www.digitalcalculator.info/mcp/reports/  
**Last Updated**: 2026-11-13

The `generate_report` tool renders a PDF report for a calculator scenario on our servers and returns a short-lived download link. Use it when an agent or a backend needs to hand someone a finished document. A paid key can carry your branding, so every report it renders shows your name, logo and colours.

## What you need

-   **A paid key** (`dc_bearer_`), sent as `Authorization: Bearer dc_bearer_…` on every call. See [API keys](https://www.digitalcalculator.info/mcp/keys/#paid-key). A free `dc_pub_` key and anonymous calls do not unlock the tool: without a paid key it is missing from `tools/list`, and calling it anyway returns `authentication_required`.
-   **A server, not a web page.** Call from a backend, a command-line tool or an MCP client, and keep the key out of anything a browser downloads.
-   **A report-capable calculator.** Five have reports: `mortgage`, `loan`, `retirement-401k`, `education` and `credit-card`.

The calculator pages on this website have their own PDF button. It builds the same kind of document in your browser, on your device, and does not use this tool.

## Call the tool

Two arguments, both required:

-   `tool` — one of the five report aliases above.
-   `input` — the same input object that calculator takes. Its field names keep their camelCase spelling (`annualRatePercent`, `termYears`), unlike the snake\_case arguments of the calculator tools, because `input` is passed to the report renderer exactly as sent ([why](https://www.digitalcalculator.info/mcp/contract/#generate-report-exception)).

Over MCP, with your paid key in the `DC_API_KEY` environment variable:

```bash
curl -X POST https://mcp.digitalcalculator.info/mcp \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $DC_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "generate_report",
      "arguments": {
        "tool": "mortgage",
        "input": {
          "principal": 400000,
          "annualRatePercent": 6.5,
          "termYears": 30
        }
      }
    }
  }'
```

Or the REST route on the same host, with the bare input object as the body. It runs the same renderer and returns the same envelope:

```bash
curl -X POST https://mcp.digitalcalculator.info/v1/reports/mortgage \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $DC_API_KEY" \
  -d '{"principal":400000,"annualRatePercent":6.5,"termYears":30}'
```

## Download the PDF

A success returns the report envelope. Over MCP the download link also arrives as a `resource_link` content block:

```json
{
  "report": {
    "url": "https://….s3.amazonaws.com/reports/mortgage/<hash>.pdf?X-Amz-…",
    "expiresInSeconds": 900,
    "cached": false,
    "contentType": "application/pdf",
    "cacheKey": "<hash>"
  },
  "tool": "mortgage",
  "engineVersion": "1.0.1",
  "calculatedAt": "2026-08-17T00:00:00.000Z",
  "disclaimer": "Estimates only — see methodology.",
  "methodology": { "url": "https://www.digitalcalculator.info/mortgage-calculator/methodology/", "version": "2026-05-09" }
}
```

-   **Fetch `report.url` before it expires.** The link lasts `expiresInSeconds`, 15 minutes by default, and cannot be guessed.
-   **Asking again is cheap.** Identical inputs are served from a cache (`cached: true`): after a link expires, the same call returns a fresh link without rendering again, and the numbers do not change.
-   **The PDF carries the detail.** The amortization table and the per-calculator figures are in the PDF; the tool result itself is a short summary.

## How reports are counted

Reports have their own daily quota on your key, 25 per UTC day by default, separate from your calculator-call allowance. The 5-minute window is shared with your other calls. When either runs out the call is refused ([what each error means](https://www.digitalcalculator.info/mcp/troubleshooting/#report-errors)). Plan allowances are on the [rate card](https://www.digitalcalculator.info/mcp/pricing/#rate-card).

## Add your branding

A paid key can carry a **BrandConfig**, stored with the key. There is no branding argument on the call and nothing to change in your code: once the key carries a BrandConfig, every report it renders is branded. All five fields are optional; any subset works.

| Field | Constraints | What it changes |
| --- | --- | --- |
| `companyName` | up to 60 characters | Replaces "Digital Calculator" as the report's branding name |
| `tagline` | up to 80 characters | Replaces the tagline under the branding name |
| `logoUrl` | `https` URL of an image (`png`/`jpg`/`gif`/`webp`/`svg`) on a public host; private or internal hosts are rejected | Adds your logo above the branding name, up to 48px tall and 180px wide |
| `primaryColor` | 6-digit hex (`#rrggbb`) | The report's main colour: header rule, branding name, results-table header bar, disclaimer bar |
| `accentColor` | 6-digit hex (`#rrggbb`) | The accent on the input summary |

**To set or change it**, include the fields when you [ask for your key](https://www.digitalcalculator.info/mcp/pricing/#request-a-key), or email [admin@markcolabs.com](mailto:admin@markcolabs.com?subject=Report%20Branding) from the address on the key. The change is saved on the key, and your next report carries it. Each field is checked on its own, so an invalid `logoUrl` drops only the logo, never the whole config. Cached reports are kept per brand, so a branding change gives fresh renders, never a report in the old branding.

Branding changes the look, never the numbers

BrandConfig changes the report's name, tagline, logo and colours and nothing else. It never changes a financial figure, an input value or a table cell, and the “Not financial advice” disclaimer stays on every branded report.

## Related

-   [`generate_report` in the API reference](https://www.digitalcalculator.info/mcp/api-reference/#generate-report) — inputs, output and every error code
-   [API keys](https://www.digitalcalculator.info/mcp/keys/) — getting, sending and storing a paid key
-   [Pricing and limits](https://www.digitalcalculator.info/mcp/pricing/) — plans and allowances
-   [Troubleshooting](https://www.digitalcalculator.info/mcp/troubleshooting/) — common errors and how to fix them

---

*Markdown copy of [https://www.digitalcalculator.info/mcp/reports/](https://www.digitalcalculator.info/mcp/reports/). For tool definitions, the hosted server's tools/list is authoritative.*
