ITWorx_MCP_Hub-Public/docs/04-mcp/COMPATIBILITY_AND_VERSIONING.md

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.