MCP Server FAQ

A hosted Model Context Protocol (MCP) server at https://mcp.digitalcalculator.info/mcp that exposes 10 tools: 9 financial calculator tools — mortgage, compound interest, 401(k), Social Security, paycheck, IRA, Roth conversion, RMD, HSA, inflation, savings, emergency fund, and loan calculations — plus money_flow_map, an interactive money-flow budget map. Connect it to claude.ai or Claude Desktop via Custom Connectors, use any Streamable HTTP MCP client, or POST JSON-RPC directly. Published by Markco Labs LLC, the company behind DigitalCalculator.info.

10 anonymous tools. Five scenario tools: plan_retirement_income (linked 401(k) + Social Security + SECURE 2.0 RMD picture), evaluate_roth_conversion (2026-bracket tax impact with break-even framing), check_contribution_eligibility (401(k) / Traditional IRA / Roth IRA / HSA limits with phase-outs), project_growth (nominal + inflation-adjusted growth), and evaluate_affordability (maximum home price at 28/36 debt-to-income targets, P&I only — added in contract 1.4.0). Four single-quantity calculators: mortgage_monthly_payment, loan_monthly_payment, paycheck_net_pay (IRS 2026 Percentage Method + FICA; state and local tax only from your own figure), and emergency_fund_recommendation. Plus money_flow_map, an interactive money-flow (Sankey) budget map. All tools return the same ToolResult envelope with provenance (rule_year, sources[]); the tools retired in the contract 1.0.0 consolidation remain callable via their REST aliases. See the API Reference for full schemas.

Yes — the anonymous tier is free to use, with no API key and no signup, and it is staying free. Note that "free" is not the same as "MIT-licensed": the hosted MCP/API service at mcp.digitalcalculator.info is a Markco Labs–operated commercial service governed by separate hosted-API terms (LICENSE-API.md — acceptable use, rate limits, no warranty). Only the npm package source (@markcolabs/mcp) is MIT-licensed open source — that’s what you self-host, modify, or embed however you want. Free calls are capped at 500 per UTC day per IP (and 30 per 5-minute window per IP), under a shared 100-requests/minute endpoint throttle. Paid tiers with larger per-key allowances are published on the pricing page. See What is the license? for the full distinction.

Use the Custom Connectors UI: open Settings → Connectors → "Add custom connector" and paste https://mcp.digitalcalculator.info/mcp. No authentication is required — the 10 tools appear in your next conversation. This replaces the old local JSON-config stdio setup. See the Quickstart for full setup instructions.

Yes — the endpoint is plain HTTP POST under the hood. Send a JSON-RPC 2.0 tools/call request with the tool name and arguments and you get the ToolResult envelope back in result.content[0].text (mirrored at result.structuredContent). A dedicated REST companion API is live at https://api.digitalcalculator.info/v1/tools/{alias}/calculate (no JSON-RPC wrapper) — see Legacy REST aliases. See Option 4 of the Quickstart.

Yes. https://mcp.digitalcalculator.info/mcp speaks the MCP Streamable HTTP transport — JSON-RPC 2.0 over HTTP POST with initialize, tools/list, tools/call, resources/list, and resources/read. Claude Custom Connectors and MCP Inspector connect to it directly. If your client only speaks MCP over stdio, the @markcolabs/mcp npm package (v0.4+) is a thin stdio→HTTPS shim to the same endpoint.

The math matches the corresponding calculators at DigitalCalculator.info to the cent. Parity tests in packages/mcp/test/parity/* enforce this on every release. Where the MCP tool intentionally narrows scope, the tool description and the methodology.url field explicitly note the limitation. For example, paycheck_net_pay does not compute state income tax for any state: it leaves the figure out (and says so) unless you pass your own annual amount in state_local_tax_annual.

Yes. Every tool response embeds a canonical YMYL (Your Money or Your Life) disclaimer in the disclaimer field of the result envelope. The same string is exposed as the dc://disclaimers/ymyl MCP resource. Tools never author their own disclaimer text — there's a single source of truth at packages/mcp/src/disclaimers/ymyl.ts. If you're building an agent that quotes the results to users, surface the disclaimer alongside the numbers.

methodology.version is the date of the last substantive update to the methodology document for that calculator. Treat it as a content version for the underlying math. Pair it with engineVersion (the code-side semver) for full audit-trail.

Per-engine SemVer constant that bumps on math changes only (not cosmetic refactors), independent of the package version. Each of the 10 tools carries its own engineVersion. Use it as a cache key.

It depends on which of two things went wrong. A tool-level error — bad input, a business-rule conflict — is a normal, successful call: HTTP 200, with result.isError: true and a single-key error object in the text content (code: one of INPUT_VALIDATION, BUSINESS_RULE, INTERNAL, RATE_LIMIT, UNAUTHORIZED; message; an optional field; retriable). Validation is never HTTP 400 — a rejected argument is a tool telling you it couldn't compute an answer, not the transport rejecting your request. On the REST route this body is always single-envelope — never double-nested. A protocol-level error (malformed JSON, unknown method, an auth or rate-limit denial on /mcp) is a different shape: a JSON-RPC error object, {"jsonrpc":"2.0","id":...,"error":{"code":<number>,"message":...,"data":{...}}}, at HTTP 401/429/etc — still one error object, never nested inside another. See Status mapping in the API Reference for every shape and status code.

result.structuredContent is the full ToolResult as a pre-parsed object — it mirrors the REST response body byte-for-byte, and it is the field to read for data. For a request without the MCP-Protocol-Version header (a plain HTTP POST, for example), result.content[0].text carries the same JSON serialized; since contract 1.7.0 a client that sends the header with 2025-06-18 or later gets a short plain-text summary there instead (see The content summary). It is present only on success: a tool-level error (result.isError: true) carries no structuredContent at all. result.resultType ("complete" on every answer; "input_required" since contract 1.5.0 when a call that declares elicitation support is missing a required input) is different — it sits beside structuredContent, not inside it, and is present on both the success and the tool-level-error result. See Envelope shapes for the full picture.

Two layers. Outer: a shared endpoint throttle of 100 requests per minute across all callers (not per-caller), burst 50 — no tier reserves throughput against it. Inner: a per-caller allowance — anonymous callers get 500 calls per UTC day per IP plus a 30-call / 5-minute short-term ceiling; Bearer keys get a per-key daily cap and short-term ceiling by plan (see the rate card). Only tools/call counts against either ceiling — connecting, listing tools, and reading resources are free and can never be throttled. Either ceiling returns HTTP 429: the REST route's body is {"error":{"code":"RATE_LIMIT","retriable":true,...}}; on /mcp it's a JSON-RPC error object, code -32000, with the throttle facts in error.data. The npm package over stdio runs locally and isn't rate-limited itself — it proxies to the hosted endpoint, so the hosted limits still apply.

Yes, with backoff — and read the response headers first. A 429 carries Retry-After plus X-RateLimit-Limit / -Remaining / -Reset, unchanged regardless of which body shape you got; honor Retry-After rather than guessing. A shared-throttle 429 clears within a minute; a per-IP window 429 clears at the next 5-minute boundary; a daily-cap 429 clears at UTC midnight. If you're throttled during a connect sequence, check that you're calling tools/call too eagerly — initialize, tools/list, and the rest of discovery never count against the window. If you are legitimately hitting the daily cap, that is the signal to move to a Bearer key — or email us and we'll help size the tier.

HTTP 401. On the REST route the body is the usual unwrapped {"error":{"code":"UNAUTHORIZED",...}}. On /mcp it's a JSON-RPC error object, code -32001, with the specific reason in error.data.reason: invalid_token, token_revoked, or token_expired. No rate-limit headers accompany a 401 — it isn't a throttle. Sending no Authorization header at all is not an error; that's the anonymous tier.

Snake_case is the current, advertised spelling for every tool argument (e.g., annual_rate_percent, not annualRatePercent). The four single-quantity calculator tools also still accept the older camelCase spellings — they're marked deprecated: true in tools/list and still compute correctly, adding a namespaced _meta marker to the result so you know a deprecated spelling was used. New integrations should use the snake_case names in the API Reference. The one exception is generate_report's input argument, which deliberately mirrors the REST report body's original camelCase field names — see the Amendment B exception.

Email admin@markcolabs.com. We triage weekly. Include the tool name, input that reproduces, expected vs actual output, and engineVersion from the response envelope.

Best effort, no SLA. Markcolabs is a small operation; expect ~3–5 business days for triage. Critical issues (security, accuracy regressions) get faster attention.

Per the standard .well-known/security.txt policy at /.well-known/security.txt: email admin@markcolabs.com.

Two independent version numbers cover two different surfaces — see Current version in the Changelog. The contract version (serverInfo.version from the initialize handshake, currently in the 1.x line) follows the rules on the Versioning & Deprecation Contract: PATCH is an internal fix with no observable shape change; MINOR is additive (new tools, new optional inputs with defaults, new output fields); MAJOR is anything that could break an existing client (a tool rename, a removed field, a tightened validation) and triggers the 90/180-day notice-and-coexistence process. Separately, the npm shim (@markcolabs/mcp, currently 0.4.3) versions only the optional stdio transport adapter — a shim patch does not imply a contract change, and vice versa. The shim's own tool-rename history (pre-1.0, back when it was 0.x) is in the npm version history.

MIT for the npm package source — the LICENSE file ships in the npm package (added as a standalone file in v0.2.1; copyright "Markco Labs LLC"). Self-host, modify, redistribute, embed in commercial products — all permitted. Attribution to "DigitalCalculator.info" or "Markco Labs LLC" is appreciated for AI/agent quotes but not required.

Two surfaces, two license documents. The npm package source (@markcolabs/mcp) is MIT — you can npm install it, run it over MCP stdio on your own machine, modify it, or deploy your own copy. That use is governed only by the MIT LICENSE that ships in the npm package.

The hosted endpoint at https://mcp.digitalcalculator.info/mcp is a separate Markco Labs–operated service. Calls to that URL are additionally governed by separate hosted-API terms (LICENSE-API.md, added in v0.2.1) — covering acceptable use (no scraping, no resale of raw output, no sole-authority financial decisions), the published rate limits, and a no-warranty disclaimer. If you self-host the source, LICENSE-API.md does not apply to you.

The anonymous tier is free, and we have no plans to change that. Paid tiers already exist for higher per-key allowances, attribution and support — see the rate card — but they buy allowance, identity and support, never different math: authenticated and anonymous responses are byte-identical for the same inputs. If you're interested in B2B / white-label integration, see /business/ or email admin@markcolabs.com.