MCP database tool contract versioning: stop schema drift from breaking AI workflows

An MCP database tool can keep the same name while becoming a different operation.

A required field becomes optional. A default time range changes. An enum gains a value. A result field is renamed. An error that used to mean “retry” now means “ask the user.” The server still starts, the client still discovers the tool, and the first failure may appear in a production answer.

That is contract drift. Treating tools/list as documentation alone is not enough; it is an interface that needs versioning, testing, and rollout controls.

Version behavior, not only the tool name

A useful contract includes more than JSON Schema. Record the operation identifier, input and output schemas, defaults, authorization requirements, data sources, maximum rows and bytes, timeout behavior, error taxonomy, idempotency, side effects, and policy version.

Two schemas can be structurally compatible while changing business meaning. A default moving from seven days to thirty days may pass validation and quadruple the data surface. A result changing from gross to net revenue may keep the same numeric type and invalidate every comparison.

For the broader result boundary, see tool result contracts for AI database agents.

Create a canonical contract digest

Normalize the discoverable contract into a deterministic representation and calculate a digest. Include fields that change execution semantics, not cosmetic description edits. Store that digest with deployments, client sessions, traces, and evaluation results.

A digest gives operators a stable answer to a simple question: which interface did this answer use? It also lets clients detect an unexpected change before another tool call.

Classify every diff

Use a compatibility gate rather than reviewing raw JSON by eye:

• patch: clearer descriptions or examples with no behavioral change;
• compatible extension: optional input or additive output with unchanged defaults;
• breaking: renamed or removed fields, stricter validation, changed defaults, new required scope, different error meaning, or altered side effects;
• security-sensitive: any change to tenant scope, identity, authorization, redaction, limits, data source, or mutation behavior.

Security-sensitive changes deserve an explicit review even when the schema diff appears additive.

Pin clients during a controlled rollout

Do not replace a contract everywhere at once. Publish a new operation version, keep the old version for a documented window, and route a small set of test or canary clients to the new one.

Pin long-running workflows to an approved contract digest. If the server no longer supports it, fail clearly and require rediscovery or migration. Silent fallback is attractive during an outage but can erase the evidence needed to explain changed behavior.

For deployment controls around AI database access, use the AI database access governance checklist.

Replay real tool calls against the candidate

Build a sanitized replay set from representative normalized requests and known edge cases. Compare:

• validation and clarification behavior;
• selected source, tenant, role, and policy;
• generated query or approved operation;
• row and byte counts, truncation, and redaction;
• error code and retry guidance;
• latency, cancellation, and database cost;
• final result shape and provenance.

Do not require byte-for-byte equality for changing data. Compare the contract invariants that must remain stable.

Concrete example: changing a customer-health tool

Version 3 accepts an account ID and a 30-day maximum window. It returns an approved risk category, evidence timestamp, and up to ten redacted signals.

Version 4 adds region as an optional filter. That looks additive. But if an omitted region now means “all regions” instead of “the user’s authorized region,” the change is security-sensitive and breaking in practice.

The safe rollout preserves version 3, derives region from trusted user context in version 4, replays cross-region tests, and records both the contract and policy digest with every result.

Design deprecation as an operational process

1. Announce the replacement and exact incompatibilities.
2. Expose usage by client and contract version.
3. Provide fixtures and migration examples.
4. Set a deprecation date and alert active consumers.
5. Block new adoption of the old version before removal.
6. Retire only after usage reaches the agreed threshold.
7. Keep enough metadata to reconstruct historical answers.

A version is not retired merely because a new server image shipped.

Where Conexor fits

Conexor provides MCP infrastructure for connecting AI clients to databases and APIs through governed tools. Versioned contracts, explicit limits, provenance, and rollout evidence help teams change those tools without turning interface drift into data-access drift.

Explore MCP server architecture and comparison

For runtime evidence, see audit-ready MCP database workflows.