MCP Tool Versioning & Deprecation Contract
A written commitment about what we won’t break on mcp.digitalcalculator.info/mcp, when we’ll tell you before we do, and how we check it before every release. If you’re integrating our MCP server into a production system, this page tells you exactly what stability you can count on. For the full technical specification, see the API Reference for per-tool schemas.
Our Promise
Our MCP server is designed for AI agents that make financial decisions. That only works if the shape of our answers stays predictable. So we make three promises:
- We will not silently change the shape of any tool. Every input parameter and every output field on
mcp.digitalcalculator.info/mcpis versioned. Changes that could break your code trigger a version bump and a deprecation notice. - We will not remove or rename anything without notice. Anonymous callers get at least 90 days notice; Bearer-tier customers get at least 180 days notice. During the notice window and for at least 60 days after, both the old shape and the new shape work.
- We check this automatically, not just in documentation. Every release is checked against a snapshot of every tool’s input and output schema and a baseline of real tool calls. If either changes without an intentional version bump, the release does not ship.
- We will not break the REST aliases — ever. Every REST alias that has ever existed at
api.digitalcalculator.info/v1/tools/{alias}/calculatekeeps working indefinitely with its original request/response shapes, including the aliases of tools that were consolidated into the scenario tools. The REST twin is where backward compatibility lives permanently, untouched by the MCP-side move to snake_case argument names; see the alias table.
Release history in brief
Contract 1.0.0 (2026-08-07) consolidated the anonymous surface into 9 tools — four scenario tools plus the kept calculators and money_flow_map — and added the provenance fields (rule_year, sources[]), reference-data resources and prompts. It was made under the 0.x rules, which allowed breaking changes, so that the surface directory listings froze would be the intended one; the promises on this page bind every release from 1.0.0 on. Every release since has been additive (MINOR) or a correction (PATCH), except 2.0.0, the one MAJOR release, whose notice window was waived and disclosed. The release-by-release detail is in the changelog, and the serverInfo.version field of the live initialize handshake always names what production is running.
Upcoming changes
Every announced change that will refuse or remove something answered today, with the earliest date it can ship. Each links to its notice below.
| Earliest date | Change | Announced |
|---|---|---|
| 2027-05-23, and only after 90 days with no request using a camelCase argument name | The camelCase argument spellings and output keys are removed | 2026-09-25 |
| 2027-05-27 | Out-of-range arguments are refused | 2026-09-29 |
| 2027-05-27 | initialize stops answering protocol 2026-07-28 | 2026-10-09 |
Versioning Rules
The MCP contract version is carried in the serverInfo.version field returned by the initialize handshake. It follows Semantic Versioning 2.0.0. This is the version of the contract, and it is deliberately distinct from the shim npm package version (@markcolabs/mcp) and from the internal deploy stack version.
| Bump | When it happens | Worked example |
|---|---|---|
| MAJOR | A change that could break an existing client. Removing a tool, renaming a tool, removing an input parameter, renaming an output field, changing an output field’s type, or tightening an input validation so previously-accepted inputs are now rejected. | Renaming mortgage_monthly_payment.monthlyPayment → monthlyPi. Existing code reading result.monthlyPayment would break, so this is MAJOR — and it would trigger the full notice + coexistence process below. |
| MINOR | An additive change that a compliant existing client keeps working through unchanged. New tools, new optional input parameters with documented defaults, new output fields, or expanding an input validation so previously-rejected inputs are now accepted. | Adding an optional catchUpEnabled: boolean parameter to retirement_401k_projection with default false. Clients that omit the field get the pre-existing behavior; clients that supply it get the new option. |
| PATCH | Internal changes that do not alter any observable contract surface. Engine formula refinements that keep the same output shape, bug fixes that bring outputs closer to specified behavior, performance improvements, documentation edits. | Refining an engine’s math to match a corrected IRS interpretation while keeping the same output field names and types (for example, a corrected rounding or eligibility rule). |
Two more version fields travel in every result, independently of the contract version: engine_version, a per-tool SemVer that moves only when that tool’s math changes, and methodology.version, the date the tool’s methodology page was last materially updated.
Anonymous-parity note
A change that looks additive (MINOR) but causes the response to an anonymous caller to differ byte-for-byte from what it was before is treated as MAJOR — unless the change is scoped exclusively to authenticated responses. Bearer-tier feature additions cannot leak into the free anonymous tier. See Anonymous-Parity Guarantee.
Deprecation Policy
When we bump MAJOR, we commit to the following notice + coexistence process before the old shape is removed:
| Caller | Minimum notice before removal | Coexistence after notice window |
|---|---|---|
Anonymous tier (no Authorization header) |
90 days | ≥ 60 days with both shapes working |
| Bearer tier (authenticated) | 180 days | ≥ 60 days with both shapes working |
The Bearer window is longer because Bearer customers integrate the endpoint into production systems with change-management cycles measured in months. Anonymous callers are typically experimenting; they can pivot faster. The 90-day floor is still non-trivial — a developer who evaluates the endpoint anonymously and then upgrades to Bearer should not be surprised by a shape change 30 days in.
Every MAJOR bump publishes:
- A dated deprecation notice on this page under Upcoming changes.
- A notice in the deprecated tool’s MCP
descriptionfield — visible to any client that callstools/list. - An
X-DeprecationHTTP response header on the deprecated tool’s responses. Not every MCP client surfaces response headers, but this is machine-readable for those that do. - For Bearer-tier customers: a direct email to the address on file.
Emergency exception
A security fix or regulatory-compliance obligation that requires a breaking change without the full notice window MAY ship immediately. In that case the change is published here on the day of the deploy and affected customers are emailed directly. This exception is not routine — it exists so we can act on genuine security issues without waiting six months.
Notice waived and disclosed: 2.0.0
2.0.0 is a MAJOR change: in paycheck_net_pay, five output fields that were always numbers or booleans (state_tax, state_tax_annual, state_effective_rate_percent, state_tax_source, no_state_income_tax, with their camelCase twins) may now be null. The 90-day notice and the coexistence window were waived, and are disclosed here, because the release withdraws a state-tax figure that could be materially wrong on a tax question; keeping it published for the notice period was the greater risk. We decided this on 2026-09-26. Nothing was removed or renamed, and every call that worked before still works. See the changelog.
Argument deprecation notice: camelCase spellings
The 17 camelCase input arguments on the four single-quantity calculator tools are deprecated in favor of a snake_case spelling: mortgage_monthly_payment (2 arguments), loan_monthly_payment (3), paycheck_net_pay (6), and emergency_fund_recommendation (6). Each tool’s input table in the API Reference names the deprecated spelling beside its replacement. The server’s deprecation marker links here.
- Both spellings are accepted. This is additive under the rules above (a MINOR change, not MAJOR) — the old spelling still computes the same answer.
- The deprecated spelling is marked in the schema.
tools/listlists the camelCase property with the JSON Schemadeprecated: truekeyword, so a client reading the live schema can see the notice without reading this page. - Using the old spelling still works, with a marker. A request using a deprecated spelling computes its answer normally and adds a namespaced
_metafield to the result:result._meta["info.digitalcalculator/deprecatedArguments"], naming which field(s) were re-spelled. - Both spellings, different values, is rejected. If a request somehow supplies both the snake_case and camelCase spelling of the same field with different values, the server does not silently prefer one — it fails closed with the existing
INPUT_VALIDATIONshape. - Removal is scheduled by rule. The camelCase spellings are removed together with the camelCase output keys, under the rule in Upcoming changes. Until then both spellings keep working, and the deprecated properties’ descriptions and the
_metamarker (itsremovalfield) carry the rule.
Upcoming changes: removing the camelCase names (announced 2026-09-25)
Every result carries one naming convention: a snake_case twin beside every camelCase output key, a whole-number *_percent field for every rate or ratio, and an inputs echo. The names it replaces will be removed in a later MAJOR release:
- What is removed: the 17 camelCase argument spellings listed above; every camelCase key in
structuredContent(for examplemonthlyPayment,yearByYear,calculatedAt), which includes every decimal-ratio key (monthlyRate,marginalRateOnConversion,effectiveRateOnConversion,stateEffectiveRate); andwarnings[].field, replaced bywarnings[].argument. The output schemas mark each removed propertydeprecated: true, and the API Reference lists every name and its replacement. - When: no earlier than 2027-05-23. The removal is a MAJOR release, so the notice and coexistence windows above apply: the 180-day notice plus the 60-day coexistence window, counted from this announcement on 2026-09-25. That is later than the server’s own rule (2 minor versions or 60 days after production serves contract 1.8.0, which allowed 2026-11-26), so it governs.
- Only when unused: the names are removed only after 90 days in which no request has sent a camelCase argument name. If requests still use them, the date moves later and the Upcoming changes table says so.
- What to do now: send the snake_case argument names and read the snake_case and
*_percentkeys. Both are live today, so a client that moves now is unaffected by the removal. - Not affected: the legacy REST aliases, which keep their wire shapes indefinitely, and enum values such as
"fullyDeductible", which keep their spelling.
Upcoming changes: refusing out-of-range arguments (announced 2026-09-29)
Every numeric argument documents its accepted range in the tool’s inputSchema, and almost every range is enforced: a value outside it is refused with INPUT_VALIDATION. A value that is answered anyway will be refused too, in a later MAJOR release:
- What changes: a numeric argument outside its documented range (its minimum, its maximum, or a whole-number requirement) is refused with
INPUT_VALIDATIONinstead of answered. Today this affects one argument:paycheck_net_pay’s legacydependents, documented as a whole number from 0 to 20. - When: no earlier than 2027-05-27, which is the 180-day notice (the Bearer-tier window, the longer of the two above) plus the 60-day coexistence window, counted from this announcement; and no earlier than 180 days after production first serves contract 2.5.0. Whichever date is later governs.
- Until then: the value is answered as before, and the answer carries a
warnings[]entry withcode: "input_out_of_range"naming the argument, the value and the accepted range. The argument’s description intools/listcarries the date. - What to do now: send values inside the documented range. For
dependents, send a whole number from 0 to 20, or usechildren_under_17andother_dependents.
Upcoming changes: initialize stops answering protocol 2026-07-28 (announced 2026-10-09)
Protocol revision 2026-07-28 is reached through server/discover and a per-request envelope (params._meta carrying io.modelcontextprotocol/protocolVersion) rather than through initialize. Today this server still answers initialize with 2026-07-28 when a client asks for it, and a client that connects that way then sends MCP-Protocol-Version: 2026-07-28 without the envelope, so its requests skip that revision’s request checks. Closing that gap refuses requests that are answered today, so it is a MAJOR change under the rules above:
- What changes: a client that sends
initializeasking for2026-07-28is answered with2025-11-25, the newest revision that usesinitialize. A request that sendsMCP-Protocol-Version: 2026-07-28without the per-request envelope is refused with an HTTP 400 JSON-RPC error instead of answered. - When: no earlier than 2027-05-27, 230 days after this announcement, which is longer than the 180-day notice the policy above sets for the Bearer tier.
- Until then: both requests are answered as they are today. The new behavior is already available:
initializeasking for2025-11-25, andserver/discoverwith the envelope on every request, work now and do not change. - What to do now: to use revision 2026-07-28, connect with
server/discoverand send the envelope and its matching headers on every request. To keep usinginitialize, ask for2025-11-25, and send the version the server answers inMCP-Protocol-Version. - Not affected: tool inputs and outputs, and requests that send no
MCP-Protocol-Versionheader or name2025-11-25or2025-06-18.
The generate_report.input exception
generate_report’s input argument is a documented, permanent exception to the snake_case argument policy above: it is not re-spelled, and carries no deprecated-argument aliases. input is the POST /v1/reports/{tool} REST report body, carried verbatim to the report renderer, so the REST surface stays exactly as documented. Three of the five report-capable tool aliases (retirement-401k, education, credit-card) have no snake_case MCP tool, so there is no snake_case vocabulary to alias them to. additionalProperties: false is still enforced on generate_report’s own top level (tool, input); it is input’s own contents that stay an open, un-aliased object matching the REST wire.
Anonymous-Parity Guarantee
Every request without an Authorization header must return byte-for-byte the same response body as it would have returned before Bearer tier existed. That is what we mean by anonymous parity: the free tier does not silently regress when we ship paid features. It matters because the anonymous tier is how developers evaluate our server before they buy — if the evaluation drifts, the buy decision does too. We check it with a baseline of real tool calls made with no Authorization header, run before every release, so any paid-tier addition that leaks into anonymous responses stops the release.
What This Doesn’t Cover
- The REST companion endpoint at
api.digitalcalculator.info/v1/…uses URL-path versioning (/v1/,/v2/) rather thanserverInfo.version. Its alias-compatibility guarantee (every alias works indefinitely, original wire shapes preserved) is stated above and in the API Reference. - Pricing tiers, quotas, and SLA commitments live on the pricing page and in the Bearer-tier terms. Changes to those are not contract changes governed here unless they change a tool’s
inputSchemaor output. - Uptime SLAs. This is a stability contract about the shape of our answers, not a guarantee about how often the endpoint is reachable. Availability commitments for Bearer tier are in the Bearer terms.
- The
@markcolabs/mcpnpm shim is versioned separately. A shim PATCH does not imply a contract change; a contract MINOR does not imply a shim change.
FAQ
What is the current contract version?
The version is returned in the serverInfo.version field of the initialize handshake response. Point any MCP client at https://mcp.digitalcalculator.info/mcp and read the field. That is the canonical answer — it can never disagree with what the server is actually running.
Does adding a new tool require a MAJOR bump?
No. Adding a tool is additive — it is a MINOR bump. Existing clients that were not calling the new tool continue to work with no change. Removing or renaming an existing tool is what triggers MAJOR.
What counts as a “shape change” that requires notice?
Any change a compliant client would notice on the wire: a field disappearing, a field changing type, a field being renamed, an input value that used to be accepted now being rejected, or a tool being removed / renamed. Engine math refinements that keep the same output field names and types are PATCH — not shape changes — and do not require notice. The per-tool engine_version field in every response tells you when the math has been refined.
Where do I subscribe to deprecation notices?
Check Upcoming changes on this page and the changelog; if you’re a Bearer-tier customer, also watch the email on your account. There is no RSS or email subscription yet.
How do I know you’re actually enforcing this?
Before every release, two checks run: a schema snapshot of every tool’s input and output, and a baseline of real tool responses. Either one failing stops the release. To change a shape, we have to update the snapshot in the same change, which is where the version bump is checked against the kind of change. The baseline was first captured in June 2026.
What if you discover a serious contract-design flaw after Bearer customers are onboarded?
The 180-day Bearer notice window is by design — fixing a design flaw takes six-plus months from notice to full cutover. That’s the cost of the promise’s value. Security or regulatory fixes ship faster under the emergency exception; other design flaws wait for the coexistence window.
See Also
- API Reference — per-tool schemas, output shapes, and error codes (the technical surface this contract governs)
- MCP Server hub — overview + connection options
- Quickstart — connect and make your first call
- FAQ — accuracy, support, and general questions