API Reference

Hosted MCP server at https://mcp.digitalcalculator.info/mcp (Streamable HTTP, POST, no auth required — optional Bearer tier) · all 13 calculator tools with input schemas, output payload shapes, and error codes. Hosted-API terms: see LICENSE-API.md (acceptable use, rate limits, no warranty). Two additional tools, generate_report and money_flow_map, are available to Bearer-tier sessions only.

Calling the server

The server speaks the MCP Streamable HTTP transport: JSON-RPC 2.0 over HTTP POST. Supported methods: initialize, ping, tools/list, tools/call, resources/list, resources/read. A tool invocation looks like:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "mortgage_monthly_payment",
    "arguments": { "principal": 300000, "annualRatePercent": 6.5, "termYears": 30 }
  }
}

Successful calls return a JSON-RPC envelope whose result.content[0].text contains the ToolResult JSON described below. Tool failures set result.isError: true with the ToolError JSON in the same content slot.

Envelope shapes

ToolResult<T> (success)

interface ToolResult<T> {
  result: T;                          // Tool-specific structured object
  disclaimer: string;                 // Canonical YMYL disclaimer
  methodology: {
    url: string;                      // Absolute URL to calculator's methodology page
    version: string;                  // ISO date of last substantive update
  };
  calculatedAt: string;               // ISO-8601 UTC timestamp
  engineVersion: string;              // SemVer of engine that produced result
}

ToolError (failure)

interface ToolError {
  error: {
    code: "INPUT_VALIDATION" | "BUSINESS_RULE" | "INTERNAL" | "RATE_LIMIT";
    message: string;                  // Human-readable
    field?: string;                   // Input field that failed (validation only)
    retriable: boolean;               // Only RATE_LIMIT is retriable
  };
}

Status mapping

• 200 + ToolResult — success
• 200 + isError: true — tool-level error (INPUT_VALIDATION, BUSINESS_RULE) per the MCP spec
• JSON-RPC error object — malformed request, unknown method (protocol-level errors)
• 429 — RATE_LIMIT (endpoint throttle)
• 500 — INTERNAL (shouldn't happen in production; report it if you see one)

All error payloads are single-envelope {"error":{"code":...}} — never double-nested.

Tool naming convention

Tool names are snake_case: <calculator>_<output> (e.g., mortgage_monthly_payment). The legacy dot-notation names from the v0.2.x stdio package (dc.calculator.mortgage.monthlyPayment) were retired at the hosted-server cutover — dot-notation tool names break Claude Connectors' tool-name validation.

Tool index (13 tools)

mortgage_monthly_payment

Compute the monthly principal & interest payment, total interest paid, and total amount paid over the life of a fixed-rate mortgage. loan_monthly_payment is a parallel principal-&-interest calculator; both use the same amortization formula and return identical numbers for the same principal/rate/term. Neither models down payment, PMI, property tax, or homeowners insurance — pick by vocabulary (principal here vs loanAmount there).

Input schema

Output payload

{
  "monthlyPayment": 1896.20,
  "totalInterest": 382633.47,
  "totalPaid": 682633.47
}

compound_interest_future_value

Project the future value of an initial principal with optional regular monthly contributions, compounding at the chosen frequency. savings_future_balance is the same calculation pinned to monthly compounding (param mapping: principal=initialDeposit, annualRatePercent=annualInterestRate, futureValue=finalBalance, interestEarned=totalInterestEarned); use this tool when the caller needs a non-monthly compounding frequency.

Input schema

Output payload

{
  "futureValue": 106639.02,
  "totalContributions": 70000.00,
  "interestEarned": 36639.02
}

retirement_401k_projection

Year-by-year 401(k) projection through retirement. Honors IRS 2026 contribution limits including SECURE 2.0 super-catch-up for ages 60–63.

Input schema

Cross-field rule: retirementAge > currentAge (returns INPUT_VALIDATION if not).

Output payload

{
  "futureBalance": 1363230.16,
  "totalContributions": 369362.00,
  "employerContribTotal": 114181.00,
  "growthEarned": 854687.17,
  "yearByYear": [
    { "year": 1, "age": 36, "employeeContribution": 4800.00, "employerMatch": 2400.00, "growth": 1750.00, "endingBalance": 33950.00 }
  ]
}

IRS 2026 limits applied

• Base employee deferral: $24,500
• Catch-up (ages 50–59 or 64+): $8,000
• Super catch-up (ages 60–63, SECURE 2.0 § 109): $11,250
• Total with regular catch-up: $32,500; with super catch-up: $35,750

social_security_estimated_benefit

Estimate Social Security retirement benefits using the SSA bend-point formula and a simplified AIME approximation. Includes early-claim reduction, delayed-credit math, and lifetime benefit projection.

Input schema

Output payload

{
  "monthlyBenefitAtFRA": 2132.40,
  "adjustedMonthlyBenefit": 2132.40,
  "lifetimeBenefitProjection": 460598,
  "fraAge": 67.0,
  "eligibilityYear": 2027,
  "bendPointsEstimated": true
}

paycheck_net_pay

Estimate net (take-home) pay per paycheck using the IRS 2026 federal Percentage Method, FICA (Social Security 6.2% + Medicare 1.45% + Additional Medicare 0.9% above thresholds), and a state-aware tax estimate.

Input schema

Output payload

{
  "grossPerPaycheck": 3076.92,
  "federalTax": 299.65,
  "ficaTax": 221.26,
  "stateTax": 114.33,
  "netPay": 2257.07,
  "payPeriodsPerYear": 26,
  "federalTaxAnnual": 7791.00,
  "ficaTaxAnnual": 5752.80,
  "stateTaxAnnual": 2972.50,
  "netPayAnnual": 58683.70,
  "noStateIncomeTax": false
}

ira_contribution_limit

Compute the eligible IRA contribution for 2026 given age, filing status, MAGI, and IRA type. Applies the IRS age-50+ catch-up and the Roth IRA MAGI phase-out per IRC §408A(c)(3). For Traditional IRAs, the contribution limit is not MAGI-gated — only deductibility is, surfaced as traditionalDeductionStatus. Deductibility under IRC §219(g) depends on whether the filer (or spouse, for joint filers) is covered by a workplace retirement plan: supply the optional workplaceCoverage / spouseWorkplaceCoverage flags for the correct phase-out, or omit them and the status assumes no coverage (fully deductible, flagged indicative-only via traditionalDeductionNote).

Input schema

Output payload

{
  "eligibleContribution": 8600.00,
  "traditionalCap": 8600.00,
  "rothCap": 8600.00,
  "catchUp": 1100.00,
  "phaseOutReduction": 0,
  "catchUpEligible": true,
  "traditionalDeductionStatus": "fullyDeductible",
  "traditionalDeductionNote": "Assumes NEITHER you nor your spouse is an active participant…",
  "meta": { "taxYear": 2026 }
}

roth_conversion_tax_impact

Compute the federal income tax impact of a single Roth conversion using 2026 IRS brackets. Returns the incremental tax owed, the top marginal bracket the conversion pushes you into, the effective rate on the conversion, a Roth 5-year-rule flag (age < 59½), and optional break-even years when you supply your expected retirement marginal rate.

Input schema

rmd_distribution_amount

Compute the 2026 required minimum distribution from a Traditional IRA / 401(k) / 403(b) / 457(b) given the prior year-end balance and the owner's age. Applies the IRS Uniform Lifetime Table (Pub. 590-B Table III) and reports the SECURE 2.0 §302 missed-RMD excise tax (25%, reduced to 10% if corrected within the IRS correction window).

Input schema

Output payload

{
  "rmdAmount": 18867.92,
  "distributionPeriod": 26.5,
  "lifeExpectancyFactor": 26.5,
  "tableUsed": "uniform-lifetime",
  "penaltyIfMissed": { "defaultPercent": 25, "correctedPercent": 10 },
  "jointLifeTableMayApply": false,
  "spouseBeneficiaryNote": "Computed with the Uniform Lifetime Table (Table III)…",
  "meta": { "taxYear": 2026 }
}

hsa_contribution_limit

Compute the annual HSA contribution limit for 2026 given age, HDHP coverage tier, and optional employer contribution. Applies IRS Rev. Proc. 2025-19 limits ($4,400 self-only, $8,750 family) plus the statutory $1,000 catch-up for age 55+ (IRC §223(b)(3)(B)). Employer contributions reduce the employee's remaining room dollar-for-dollar.

Input schema

Output payload

{
  "contributionLimit": 4400.00,
  "catchUpEligible": true,
  "catchUpAmount": 1000.00,
  "totalContributionLimit": 5400.00,
  "employerContribution": 1000.00,
  "employeeMaxRemaining": 4400.00,
  "payrollDeductionTaxSavings": 968.00,
  "employerContributionExceedsLimit": false,
  "excessContribution": 0,
  "meta": { "taxYear": 2026 }
}

inflation_adjusted_value

Compute the inflation-adjusted value of an amount over N years. Two modes: future_value (how many future dollars match today's purchasing power) or purchasing_power (what today's amount is worth in real terms after N years of inflation).

Input schema

Output payload

{
  "adjustedAmount": 14185.19,
  "totalInflation": 41.85,
  "annualRate": 3.5,
  "years": 10,
  "mode": "future_value"
}

savings_future_balance

Compute the future balance of a savings account with an initial deposit, optional monthly contributions, and a fixed annual interest rate using monthly compounding. Mirrors the site's savings calculator engine. This is compound_interest_future_value pinned to monthly compounding — use that tool for a different compounding frequency.

Input schema

Output payload

{
  "finalBalance": 47291.36,
  "totalContributions": 41000.00,
  "totalInterestEarned": 6291.36,
  "years": 5
}

emergency_fund_recommendation

Compute a personalized emergency-fund target and savings timeline. The recommended coverage months come from the household employment situation (employed dual-income with no dependents = 3 months; standard employed = 6; self-employed/freelance = 9; between jobs = 12), then the tool calculates the funding gap, the months-to-goal at your savings rate, and interest earned if a HYSA APY is provided. Mirrors the site's emergency fund calculator engine exactly.

Input schema

Output payload

{
  "recommendedMonths": 9,
  "targetFund": 40500.00,
  "currentSavings": 8000.00,
  "fundGap": 32500.00,
  "percentComplete": 19.8,
  "monthsToGoal": 51,
  "interestEarned": 1693.42,
  "futureValue": 40500.00
}

loan_monthly_payment

Compute the monthly payment, total interest, and total paid for a fixed-rate amortizing loan (personal, auto, student, etc.) via the standard amortization formula. Zero-interest loans are handled as simple principal division. Mirrors the site's loan calculator engine exactly. mortgage_monthly_payment is a parallel principal-&-interest calculator for home loans; both compute P&I only — neither models down payment, PMI, property tax, or homeowners insurance.

Input schema

Output payload

{
  "loanAmount": 25000.00,
  "annualRatePercent": 8.5,
  "termYears": 5,
  "numPayments": 60,
  "monthlyRate": 0.0070833,
  "monthlyPayment": 512.92,
  "totalPaid": 30775.43,
  "totalInterest": 5775.43
}

Bearer-tier tool: generate_report

Renders a vector-text PDF report for a report-capable calculator tool and returns a short summary plus a short-lived presigned download link. Uses the same rendering pipeline as the Bearer-gated REST endpoint POST /v1/reports/{tool} (ADR-0055), metered against a daily report quota that is SEPARATE from the calculator-call quota.

Input schema

Output

On success, the tool returns an MCP content array with a short text summary followed by a resource_link content block pointing at the presigned PDF URL, plus a structuredContent object mirroring the REST report envelope:

{
  "report": {
    "url": "https://&hellip;.s3.amazonaws.com/reports/mortgage/<hash>.pdf?X-Amz-&hellip;",
    "expiresInSeconds": 900,
    "cached": false,
    "contentType": "application/pdf",
    "cacheKey": "<hash>"
  },
  "tool": "mortgage",
  "engineVersion": "1.0.0",
  "calculatedAt": "2026-07-06T00:00:00.000Z",
  "disclaimer": "Estimates only &mdash; see methodology.",
  "methodology": { "url": "https://www.digitalcalculator.info/mortgage-calculator/methodology/", "version": "2026-05-09" }
}

The presigned URL is short-lived (15 minutes by default) and unguessable. The rendered PDF carries the full numeric detail (amortization table, per-tool figures) — the tool result intentionally returns a short summary, not a re-derivation of the underlying calculator's output.

Errors

• authentication_required — no (or an invalid) Bearer token; anonymous callers always get this
• report_quota_exceeded — the key's separate daily report quota (default 25/day) was exceeded
• rate_limited — the shared 5-minute per-key rate window was exceeded
• REPORT_UNAVAILABLE — the tool alias isn't (yet) report-capable; the message names the currently supported aliases
• INPUT_VALIDATION — missing tool / input, or the target tool rejected input
• INTERNAL — report generation failed; report it if you see one

Bearer-tier tool: money_flow_map

Turns a structured monthly budget — income sources and spending categories, optionally broken into line items — into a deterministic computed summary plus mapUrl, a shareable deep link that renders the budget as an interactive Sankey money-flow map on the Money Flow Visualizer instantly (no account, nothing stored server-side). Built for conversational budgeting: the calling model interviews the user, structures the answers, and hands back the map link. The tool is read-only and deterministic like the 13 calculator tools — it accepts no free text and does no interpretation. All amounts are MONTHLY USD. Methodology: How This Tool Works.

Input schema

Validation is strict: unknown fields anywhere in the input are rejected with INPUT_VALIDATION, as are negative, non-finite, or out-of-range amounts.

Output payload

Returns the standard ToolResult envelope (disclaimer, methodology, calculatedAt, engineVersion) whose result is:

{
  "label": "Saving for a house",
  "totalMonthlyIncome": 6600,
  "totalMonthlySpending": 3130,
  "monthlySavings": 3470,
  "deficit": false,
  "savingsRatePercent": 52.5757575757…,
  "categories": [
    { "label": "Housing", "monthlyTotal": 2030, "percentOfIncome": 30.7575… },
    { "label": "Food", "monthlyTotal": 700, "percentOfIncome": 10.6060… }
  ],
  "largestCategories": [ { "label": "Housing", "monthlyTotal": 2030, "percentOfIncome": 30.7575… } ],
  "mapUrl": "https://www.digitalcalculator.info/money-flow-visualizer/#s=<base64url>"
}

• monthlySavings is the residual (income − spending) and may be negative; deficit is true when spending exceeds income — the map shows a deficit banner instead of an invented savings flow
• savingsRatePercent = savings ÷ income × 100 (0 when income is 0); percentOfIncome uses the same convention
• largestCategories lists up to the 3 largest categories by monthly total, descending
• mapUrl encodes the budget in the visualizer’s versioned v1 URL-state schema (#s=<base64url(JSON)>) — opening it renders the interactive map client-side; nothing is uploaded or stored
• Monetary values are full floating-point precision (not pre-rounded) — display-round to cents

Errors

• authentication_required — no (or an invalid) Bearer token; anonymous callers always get this
• INPUT_VALIDATION — empty/missing incomes, out-of-range or non-finite amounts, over-cap list lengths, unknown fields, or a category with both amount and items (the field property names the offending path)
• INTERNAL — computation failed; report it if you see one

Resources

The MCP server exposes 2 resources:

dc://disclaimers/ymyl

The canonical YMYL disclaimer string returned in every tool response's disclaimer field. Read this resource if you want to embed the same disclaimer alongside agent-generated summaries of MCP results.

dc://methodologies/manifest

A JSON manifest mapping each of the 13 anonymous calculator tools to the methodology URL of its source calculator on digitalcalculator.info. Use it for agent-side citation of where each formula and its assumptions are documented. Bearer-tier tools are not listed in the manifest — they carry their methodology URL in their own tool responses (and on this page).

Rate limits

• Anonymous tier: a global API Gateway throttle of about 100 requests/minute (burst 50) shared across all anonymous callers — per-API, not per-IP. Exceeding it returns HTTP 429 + code: "RATE_LIMIT" (retriable: true). Terms: LICENSE-API.md
• Bearer tier: per-key fixed-window (boundary-aligned 5-minute buckets) and daily quotas by plan — authenticate with an Authorization: Bearer <key> header. See plans and limits
• Bearer is server-to-server today: the API's CORS policy does not yet allow the Authorization header from browsers, so call the endpoint from a backend, CLI, or MCP client — not browser-side fetch
• Need sustained higher volume than the published tiers? Email us

Versioning

References

• Quickstart — connect + first call
• FAQ — accuracy, support, change policy
• npm package (stdio shim)
• CHANGELOG / version history (npm)
• LICENSE (MIT — package source, ships in the npm package)
• LICENSE-API.md — hosted endpoint terms (acceptable use, rate limits, no warranty)
• ADR-0039 — MCP Tool Contract (internal design doc)
• ADR-0041 — v1 Contract Reconciliation (internal design doc)

Questions or integration help: email admin@markcolabs.com.