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 our CI enforces it. 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/mcp is 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 enforce this with CI, not just documentation. Every build runs a schema-snapshot check plus a 16-call golden baseline against the live server. If either changes without an intentional version bump, the deploy fails.

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.

Semantic versioning rules for the MCP tool contract
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 (e.g., MPC-ENGINE-002, shipped in Sprint 148).

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:

Deprecation notice windows by caller tier
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 an “Upcoming changes” section (added when the first MAJOR is scheduled).
A notice in the deprecated tool’s MCP description field — visible to any client that calls tools/list.
An X-Deprecation HTTP 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.

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 enforce it with a 16-call golden baseline that runs in CI on every build; the baseline was captured with no Authorization header, so any Bearer-tier addition that leaks into anonymous responses fails the build. The technical specification is ADR-0053 § 2.4.

What This Doesn’t Cover

The REST companion endpoint at api.digitalcalculator.info/v1/… is provisioning. It will use URL-path versioning (/v1/, /v2/) rather than serverInfo.version. A separate contract will publish when REST reaches GA.
Pricing tiers, quotas, and SLA commitments live on the pricing page (when published) and in the Bearer-tier terms. Changes to those are not contract changes governed here unless they change a tool’s inputSchema or 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/mcp npm 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 engineVersion field in every response tells you when the math has been refined.

Today: check this page and, if you’re a Bearer-tier customer, watch the email on your account. A formal changelog surface with RSS + email subscription is planned but not yet live. Until it ships, this page is the single source of truth.

How do I know you’re actually enforcing this?

Every build on our stage and production pipelines runs two checks: a JSON schema snapshot of every tool’s input and output, and a 16-call golden baseline of live tool responses. Either check failing blocks the deploy. If we want to change a shape, we have to update the snapshot in the same pull request — which is where a reviewer confirms the version bump matches the change class. The baseline was published in June 2026 at qa-reports/mcp/MCP-TOOL-BASELINE-2026-06-12.md.

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.