MCP Server Quickstart

Connect the Digital Calculator MCP server to your AI tool in under 5 minutes. The server is hosted at https://mcp.digitalcalculator.info/mcp (Streamable HTTP, POST, no auth) — there is nothing to install for the recommended path.

What you'll get

9 tools — 8 calculator tools plus money_flow_map, an interactive money-flow budget map — usable directly from claude.ai, Claude Desktop, MCP Inspector, any Streamable HTTP MCP client, or plain curl. Free — no signup, no API key. The hosted endpoint is governed by its hosted-API terms (LICENSE-API.md — rate limits + acceptable use); the npm shim package is MIT-licensed (see the npm package). One additional tool, generate_report, is Bearer-tier only and renders branded PDF reports server-side — see Server-rendered PDF reports below.

Option 1 — Claude Custom Connectors (recommended)

Time: ~1 minute. Works in both claude.ai (web) and Claude Desktop. No install required.

Step 1: Open Connectors settings

In claude.ai or Claude Desktop, open Settings and go to the Connectors section.

Step 2: Add the custom connector

Click "Add custom connector" and paste the server URL:

https://mcp.digitalcalculator.info/mcp

No authentication is required — leave any auth fields blank and save.

Step 3: Confirm the tools are available

Start a new conversation and ask "what MCP tools do you have access to?" — Claude should list the 8 calculator tools plus money_flow_map (plan_retirement_income, mortgage_monthly_payment, money_flow_map, and more). If they don't appear, check that the connector is enabled in the conversation's tools menu.

Step 4: Try it

Ask Claude something like:

Example prompt

What's the monthly payment on a $400,000 mortgage at 6.5% over 30 years?

Claude will invoke mortgage_monthly_payment and return a structured answer with the math + the YMYL disclaimer.

Option 2 — MCP Inspector (for debugging)

Time: ~1 minute.

The official MCP Inspector is a browser-based debugging UI for MCP servers.

npx @modelcontextprotocol/inspector

In the Inspector UI, select the Streamable HTTP transport, enter https://mcp.digitalcalculator.info/mcp, and connect. You'll see:

All 9 tools listed in the Tools tab
The statutory reference data (dc://irs/limits/2026, dc://irs/uniform-lifetime, dc://ssa/bend-points/2026), the YMYL disclaimer (dc://disclaimers/ymyl), and the methodology manifest (dc://methodologies/manifest) in the Resources tab
The three server prompts (retirement-readiness-review, conversion-window-analysis, withholding-checkup) in the Prompts tab
The MCP protocol handshake logged in the bottom panel

Click any tool, fill the input form, and hit "Call Tool" to invoke it. Useful for verifying tool schemas before integrating in your own client.

Option 3 — npm shim for stdio-only clients

Some MCP clients and agent frameworks only speak MCP over stdio. The @markcolabs/mcp package (v0.4+) is a thin stdio→HTTPS shim: it runs locally, accepts stdio JSON-RPC, and forwards every call to the hosted endpoint.

npx @markcolabs/mcp

For frameworks like LangChain's MCP adapter or the OpenAI Agents SDK, configure the server with command: "npx" and args: ["@markcolabs/mcp"]. If your client supports Streamable HTTP natively (as Claude's Custom Connectors do), prefer Option 1 — it skips the local process entirely.

Option 4 — Plain HTTP (no MCP client needed)

Time: ~30 seconds, just curl.

The endpoint speaks JSON-RPC 2.0 over plain HTTP POST, so any HTTP client can call it. Use this for server-side scripts, CI checks, or backend fetch calls.

curl -X POST https://mcp.digitalcalculator.info/mcp \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "mortgage_monthly_payment",
      "arguments": {
        "principal": 400000,
        "annualRatePercent": 6.5,
        "termYears": 30
      }
    }
  }'

Response (HTTP 200) — a JSON-RPC envelope whose result.content[0].text contains the standardized tool result:

{
  "result": {
    "monthlyPayment": 2528.27,
    "totalInterest": 510177.95,
    "totalPaid": 910177.95
  },
  "disclaimer": "Estimates only — for educational purposes...",
  "methodology": {
    "url": "https://www.digitalcalculator.info/mortgage-calculator/methodology/",
    "version": "2026-05-09"
  },
  "rule_year": 2026,
  "sources": ["dc://methodologies/manifest"],
  "calculatedAt": "2026-08-07T18:42:11.123Z",
  "engineVersion": "1.0.0"
}

REST companion

A REST API at https://api.digitalcalculator.info/v1/tools/{alias}/calculate runs the same engines and returns the same response envelope without the JSON-RPC wrapper — including compatibility aliases for every pre-1.0 tool. See the API Reference.

Example tool calls

All examples use the same JSON-RPC tools/call wrapper — only params.name and params.arguments change. A selection across the 9 tools:

Growth projection (nominal + inflation-adjusted)

curl -X POST https://mcp.digitalcalculator.info/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"project_growth","arguments":{"balance":10000,"annual_contribution":6000,"annual_rate_percent":7,"years":30,"inflation_rate_percent":3}}}'

Linked retirement-income plan (401(k) + Social Security + RMD)

curl -X POST https://mcp.digitalcalculator.info/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plan_retirement_income","arguments":{"include":["accumulation","social_security","rmd"],"birth_year":1991,"balance":25000,"annual_salary":80000,"contribution_percent":6,"employer_match_percent":50,"employer_match_limit_percent":6,"annual_return_percent":7,"retirement_age":65,"claim_age":67}}}'

RMD-only question ("when do RMDs start?")

curl -X POST https://mcp.digitalcalculator.info/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plan_retirement_income","arguments":{"include":["rmd"],"birth_year":1968,"balance":500000}}}'

Contribution eligibility (Roth IRA with phase-out)

curl -X POST https://mcp.digitalcalculator.info/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"check_contribution_eligibility","arguments":{"kind":"roth_ira","birth_year":1974,"filing_status":"single","magi":120000}}}'

Emergency fund recommendation

curl -X POST https://mcp.digitalcalculator.info/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"emergency_fund_recommendation","arguments":{"monthlyExpenses":4500,"currentSavings":8000,"monthlySavings":600,"employmentType":"self-employed","incomeEarners":"single","dependents":2,"savingsAPY":4.3}}}'

Loan monthly payment

curl -X POST https://mcp.digitalcalculator.info/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"loan_monthly_payment","arguments":{"loanAmount":25000,"annualRatePercent":8.5,"termYears":5}}}'

For all 9 tools with full input schemas, output payload shapes, and per-tool detail, see the API Reference.

Server-rendered PDF reports (`generate_report`)

Everything above runs on the anonymous surface. One additional tool, generate_report, is available to Bearer-tier sessions only: it renders a vector-text PDF report for a report-capable calculator on our servers and returns a short-lived download link. Use it when an agent or backend needs to hand a user a client-ready document. The website's own calculator pages do not use this path — their PDF button renders the same document in the browser, on-device.

Prerequisite: a Bearer key

Every call needs an Authorization: Bearer dc_bearer_… header. dc_bearer_ keys are the secret key class — see Pricing for Bearer-tier access. The free self-serve dc_pub_ keys and anonymous sessions do not unlock this tool: without a Bearer token it is absent from tools/list, and calling it anyway returns a structured authentication_required error. Bearer calls are server-to-server today — the API's CORS policy does not allow the Authorization header from browsers — so call from a backend, CLI, or MCP client, and keep the key out of client-side source.

Step 1 — call the tool

Two required arguments: tool, a report-capable alias (mortgage, loan, retirement-401k, education, credit-card), and input, the same input object that tool's calculator accepts. Over MCP:

curl -X POST https://mcp.digitalcalculator.info/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer dc_bearer_YOUR_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 twin — same rendering pipeline, same envelope, with the bare input JSON as the request body:

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

Step 2 — download the PDF

A success returns the report envelope (over MCP, the download URL is also emitted as a resource_link content block):

{
  "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.0",
  "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 (expiresInSeconds — 15 minutes by default). Identical inputs are served from the artifact cache (cached: true): re-requesting after the link expires returns a fresh URL without re-rendering, and doesn't change the numbers. Reports are metered against a separate daily report quota on your key (default 25 per UTC day), distinct from your calculator-call allowance; the 5-minute short-term window is shared with your other calls.

Step 3 — branding (BrandConfig)

A Bearer key can carry a BrandConfig — a white-label configuration stored on the key record server-side. There is no per-request brand parameter and no code change on your side: once your key carries a BrandConfig, the same generate_report call renders the PDF with your branding. All five fields are optional; any subset works.

BrandConfig fields, their constraints, and what each changes on the rendered report
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	Adds your logo above the branding name, rendered up to 48px tall / 180px wide
`primaryColor`	6-digit hex (`#rrggbb`)	The report's slate chrome: header rule, branding name, results-table header bar, disclaimer bar
`accentColor`	6-digit hex (`#rrggbb`)	The copper accent on the input summary

To set or change it: include these fields when you request a Bearer key, or email admin@markcolabs.com from the address that requested the key to add or update them on an existing key — the change is applied to the key record, and your next render carries it. Each field is validated independently, so an invalid logoUrl drops only the logo, never the whole config. A branding change automatically produces fresh renders — the report cache is partitioned per brand, so you are never served a stale-brand PDF.

Branding is presentation-only

BrandConfig restyles the report's chrome and identity — name, tagline, logo, colors — and nothing else. It never changes a financial figure, an input value, or a table cell, and the "Not financial advice" core disclaimer is non-removable on every branded render.

Full input schema, output shape, and error codes: generate_report in the API Reference.

Common errors

`Unknown tool: <name>`

You're calling a tool name that doesn't exist. Tool names are snake_case (e.g., mortgage_monthly_payment). The legacy dot-notation names from the v0.2.x stdio package (e.g., dc.calculator.mortgage.monthlyPayment) were retired at the hosted-server cutover — if you integrated against them, switch to the snake_case names listed in the API Reference. The npm version history has full migration notes.

`INPUT_VALIDATION` with `field: "<name>"`

Input failed schema validation. The message field is human-readable ("principal must be between 0 and 100000000") and the field identifies which input. Check the API Reference for valid ranges.

`BUSINESS_RULE` error

Inputs are individually valid but the combination doesn't produce a meaningful result (e.g., 401(k) retirementAge not greater than currentAge). Fix the cross-field issue.

`RATE_LIMIT` (HTTP 429)

You hit either the shared endpoint throttle (100 requests/min across all callers) or your own per-caller allowance — anonymously, 500 calls per UTC day per IP and 30 per 5-minute window. Back off and retry: retriable: true in the error envelope, and the 429 carries Retry-After plus X-RateLimit-Limit / -Remaining / -Reset, so honor Retry-After rather than guessing. Sustained higher volume is what the Bearer tiers are for, or email us.

Next steps

API Reference — full schemas + output shapes for all 9 tools
FAQ — accuracy, YMYL posture, support, change policy
npm package — stdio shim + CHANGELOG
Contact & support — questions, feedback, integration help

Building something interesting with the MCP server? We'd love to hear about it — email admin@markcolabs.com.