API Reference

@markcolabs/mcp v0.2.1 · All 5 calculator tools with input schemas, output payload shapes, error codes, and live examples. Engine version 1.0.0. Hosted-API terms: see LICENSE-API.md.

Envelope shapes

ToolResult<T> (success — HTTP 200)

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 — HTTP 400 / 429 / 500)

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

HTTP status mapping

• 200 — ToolResult<T>
• 400 — INPUT_VALIDATION or BUSINESS_RULE
• 429 — RATE_LIMIT
• 500 — INTERNAL (shouldn't happen in production; report if you see one)

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

Tool naming convention

dc.calculator.<calculatorIdentifier>.<verb>

• dc. — fixed namespace prefix for @markcolabs/mcp. Reserved.
• calculator. — fixed taxonomy bucket.
• <calculatorIdentifier> — camelCase identifier of the source calculator.
• <verb> — camelCase noun-phrase describing the specific output.

dc.calculator.mortgage.monthlyPayment

Compute the monthly principal & interest payment, total interest paid, and total amount paid over the life of a fixed-rate mortgage.

Input schema

Output payload

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

dc.calculator.compoundInterest.futureValue

Project the future value of an initial principal with optional regular monthly contributions, compounding at the chosen frequency.

Input schema

Output payload

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

dc.calculator.retirement401k.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

dc.calculator.socialSecurity.estimatedBenefit

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
}

dc.calculator.paycheck.netPay

Estimate net (take-home) pay per paycheck using the IRS 2026 federal Percentage Method, FICA, and a simplified state-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
}

Resources

The MCP server exposes 1 resource in v0.2.0:

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.

Roadmap: dc://methodologies/<calculator> resources are planned for v0.3.0, gated on the markdown-companion strategy being live for all 5 calculators.

Rate limits

• HTTP endpoint: 100 requests/minute globally (not per-IP), burst 50
• npm stdio: no rate limit (runs on your machine)
• HTTP 429 + code: "RATE_LIMIT" when throttled

Per-IP throttling (via WAF) and per-key rate limiting (DynamoDB-backed) are deferred to future releases (filed as MCP-SEC-005 and MCP-SEC-006).

Versioning

References

• Quickstart — install + first call
• FAQ — accuracy, support, change policy
• npm package
• CHANGELOG
• LICENSE (MIT — package source)
• LICENSE-API.md (hosted endpoint terms)
• Source on GitHub
• ADR-0039 — MCP Tool Contract
• ADR-0041 — v1 Contract Reconciliation