# Compatibility and Versioning

## Tool lifecycle

- additive optional output fields are allowed within a major version;
- required input changes or semantic breaks require a new major contract;
- deprecated tools remain discoverable only for clients still bound to them and include replacement metadata;
- removals require usage evidence and an announced date.

## Gateway upgrades

A ContextForge or SDK upgrade requires:

1. backup;
2. release-note review;
3. clean-room test environment;
4. MCP discovery and invocation matrix across supported revisions;
5. auth/header/proxy tests;
6. connector contract suite;
7. rollback/restore proof;
8. recorded version/digest update.

## Client matrix

At minimum test:

- native 2026 remote MCP client;
- compatible 2025-era client;
- stdio bridge;
- MCP Inspector;
- project-bound machine client;
- revoked/invalid client negative cases.