Publishing to a directory forces a versioning question: does the tool surface stay mutable, or does it freeze into a contract?
Our surface declaration defines its draft state as "never shipped to anyone, so it is MUTABLE — breaking changes land here directly, no new stream, no deprecation." A directory listing is shipping to real clients. On a plain reading, publishing should flip it.
We decided to stay mutable, and the losing argument is the intuitive one — which is why it is worth writing down.
The case for freezing does not transfer from REST. Freezing an API version protects compiled consumers: generated SDKs, pinned clients, integration code that breaks on a rename. None of that exists on an MCP surface. Clients fetch the tool list on connect, the protocol has a list-changed notification, and an agent re-reads every description fresh each session. There is no stub to break — a rename propagates on the next connect.
And freezing costs permanently. Frozen means frozen: no fixing a weak tool description, no improving a schema. Every change then demands a second stream, and a second stream demands its own tests while the first stays frozen and still maintained. For a small team that is a standing tax paid forever, to protect consumers that do not exist.
And the surface was not stable. It went from 26 tools to 22 in a single week across two family renames. Freezing then would have frozen it mid-refactor.
⚠️ The honest residue. A catalog refresh does not fix what a human wrote that names a tool — a saved prompt, someone's skill file, your own documentation — nor cached copies of a published manifest, nor a semantic change where a field quietly changes meaning and nobody is told. But freezing does not fix those either. It only forces the change through a new version. The real question is whether you want that forcing function, and the answer depends on how many people would be protected by it.
Revisit when there is a real install base, a first paying customer, or the roster holds still for a stretch. A trigger is cheaper than a permanent freeze, and it fails safe.