Back to Resources
v1v2
Version
Deprecate
Migrate

Schema Evolution

Versioning & Migration Strategy

Schema Guide•
15 min read
•
January 20, 2025

Schema Evolution in MCP: Versioning, Deprecations, and Migrations

All Tools Directory Team
MCPSchema EvolutionVersioningMigration

Why MCP Schema Versioning Matters

MCP sits between agents and the real world. When tool contracts change, clients can fail silently, hallucinate parameters, or spam retries. A clear mcp schema versioning approach lets you ship improvements without surprise outages.

Backward-Compatible First: What Counts as a Breaking Change?

Breaking Changes (avoid or gate)

  • • Removing a field or tool
  • • Changing a field's type/format (e.g., int → string)
  • • Tightening validation (making optional → required)
  • • Renaming tools or fields without an alias
  • • Changing default behaviors with user-visible effects

Compatible Changes (safe to add)

  • • Adding optional fields with defaults
  • • Adding new enum values (if clients ignore unknown values)
  • • Adding new tools/capabilities under new names
  • • Expanding length/size limits

Rule of thumb:

If an old client can send yesterday's payload and still succeed tomorrow, it's backward compatible.

Versioning Strategy (SemVer + Capability Flags)

Semantic Versioning

  • MAJOR: breaking changes (rare; coordinate)
  • MINOR: additive features/fields
  • PATCH: bug fixes, doc clarifications

Discovery Endpoint

Expose version & features in /tools (or discovery):

{
  "contract_version":"1.7.0",
  "features":["streaming","rich-errors","next_cursor"]
}

Best Practices

  • • Prefer capability flags over version gates for behavior toggles
  • • Audience scoping: allow clients to request ?version=1.x or header X-Contract-Version: 1
  • • Error messages: include contract_version and error.path for fast triage

Deprecations: Policy, Timelines, and UX Copy

Deprecation Process

  1. Mark: add deprecated: true metadata in discovery plus a short reason and removal date
  2. Warn: log server-side on use; optionally add a soft warning field in the response (non-blocking)
  3. Document: show old/new field mapping and examples
  4. Window: typical 90–180 days before removal; longer for popular tools
  5. Notify: change log + RSS/email/Slack for integrators; pin in your SDK README
  6. Remove: major version or maintenance window; keep a temporary compat adapter if critical

UX Copy Template

field "path" is deprecated; use "paths[]" (array). Removal on 2026-09-01. See migration guide.

Migration Strategy (Adapters, Shims, and Rollouts)

Adapter Strategy

  • • Adapters at the edge: translate old requests to new shape
  • • Dual-write/dual-read: store outputs in both formats
  • • Feature flags: ship the new path dark

Rollout Strategy

  • • Canary matrix: internal → power user → 10% → 100%
  • • Observability: tag logs with client_id, contract_version
  • • Hard back-out: retain previous container image

Contract Tests for MCP (Goldens & CI)

Test Strategy

  • • Golden fixtures: versioned JSON requests/responses for each tool
  • • Schema snapshots: commit generated JSON Schemas; fail CI on breaking diffs
  • • Compatibility suite: run the full golden set in compat profiles
  • • Property tests: fuzz unknown fields; server must ignore or error clearly
  • • Latency budget tests: ensure adapters don't push p95 beyond target

Example Golden (old client)

tools/execute request (v1)

{"tool":"files.read","args":{"path":"README.md"}}

Mapped by adapter to v2

{"tool":"files.read","args":{"paths":["README.md"],"max_bytes":32768}}

Release & Rollback Playbook

Release Process

  1. Pre-release: update discovery docs; publish migration notes; ship adapters dark
  2. Canary: enable feature flag for internal client; watch error rate & adapter usage
  3. Ramp: 1% → 10% → 25% → 100%; hold if p95, error rate, or warning counts climb
  4. Remove deprecated paths: after the window closes, bump MAJOR; keep a maintenance branch for LTS users
  5. Rollback: flip feature flag off; revert image; announce post-mortem and next attempt plan

Copy/Paste Checklists

Design (before coding)

Is this a backward compatible change? If not, can it be?
New fields optional with sane defaults
Tool names stable; no silent renames
Capability flag named and documented
Discovery shows contract_version + features

Deprecation

Deprecated items labeled with reason + removal date
Server warns on use; docs show mapping
Communication plan: changelog + broadcast to integrators

Migration & Testing

Edge adapter translating v1 → v2
Golden fixtures for v1 and v2
CI schema snapshots and compat profiles pass
Observability dashboards by contract_version

Release

Feature flag & canary plan defined
Rollback image stored; runbook tested
Post-release audit: warn count trending to zero

FAQs

What's the safest way to handle breaking changes in MCP?

Avoid them. Add new optional fields or new tools; keep old ones with adapters during a deprecation window. Reserve MAJOR bumps for removals.

How long should I keep deprecated fields?

90–180 days is common. For widely used tools, keep longer and provide automated code-mod or adapter support.

How do I signal capabilities vs versions?

Expose both: contract_version for schema and features for behavior toggles. Clients can pin to a version and selectively enable features.

How do contract tests prevent regressions?

Golden request/response fixtures and schema snapshots fail CI if you remove or tighten fields unintentionally—catching breaking changes before deploy.

Key Takeaways

  • Backward compatibility first: Prefer additive changes over breaking modifications
  • Semantic versioning: Use MAJOR.MINOR.PATCH with clear deprecation windows
  • Migration strategy: Use adapters, feature flags, and canary rollouts
  • Contract testing: Golden fixtures and schema snapshots prevent regressions
  • Clear communication: Document deprecations with timelines and migration guides
  • Rollback planning: Always have a tested rollback strategy

Related Resources