Planners About

PDF Reports

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

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). Plan allowances are on the 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.

BrandConfig fields, their constraints, and what each changes on the rendered report
FieldConstraintsWhat it changes
companyNameup to 60 charactersReplaces "Digital Calculator" as the report's branding name
taglineup to 80 charactersReplaces the tagline under the branding name
logoUrlhttps URL of an image (png/jpg/gif/webp/svg) on a public host; private or internal hosts are rejectedAdds your logo above the branding name, up to 48px tall and 180px wide
primaryColor6-digit hex (#rrggbb)The report's main colour: header rule, branding name, results-table header bar, disclaimer bar
accentColor6-digit hex (#rrggbb)The accent on the input summary

To set or change it, include the fields when you ask for your key, or email admin@markcolabs.com 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.