Plain version first: when you list a server in a directory, the directory keeps its own copy of what your server is. You keep changing the server. Nothing makes the copy change with it, so sooner or later the listing describes a server that no longer exists.
I listed worklore's MCP server in the official MCP Registry on September 15 as version 0.1.0: four tools, all read-only. Two weeks later the same URL served six tools, including publish_story and report_reproduction, which write on the user's behalf. It also had new instructions and a different answer to "who can call what without signing in". The version still said 0.1.0.
I didn't notice. Sidney Bissoli did the thinking for me, in a comment thread under his article about building an MCP server for Brazil's central bank data. The Registry's server.json carries no surface at all (name, version, remotes), so against that copy the version is the only thing anyone can compare. A check like that is only as good as the habit of bumping the version, and nothing enforces the habit. His fix: hash the initialize result together with tools/list, resources/list and prompts/list, commit the hash, and fail the build when it changes without a version bump.
I added one thing he pointed out the lists don't cover: behaviour. The test also records which methods answer without a token, because no listing declares that.
To see whether it would have caught anything, I recorded the surface of the server exactly as it was when I listed it, then ran the test on today's code. It failed: "MCP surface changed (initialize, prompts/list, resources/list, tools/list) but the version is still 0.1.0." I bumped to 0.2.0, re-recorded, and republished the Registry entry. As a mutation check, adding one sentence to the instructions without a bump turns the test red.
worklore has no CI, so the deploy script now runs the suite and refuses to deploy while it's red. Writing that line, I found a second silent problem: the script never rebuilt, so every deploy shipped whatever the last manual build left behind.
What came next
A lock in my repo only protects me. A reader of Sidney's follow-up article asked the obvious next question: why not publish the hash with each release, so a client can check it too? Sidney turned that into a shared format, mcp-surface/1, with a second implementation, verify.mjs, that anyone can run against a server's Registry entry. The hash goes into server.json, and the Registry keeps it with the version.
Adopting it taught me one rule my first lock got wrong: a list that changes by itself cannot be part of a version promise. worklore's resources/list listed the stories, so its hash would change with every new story while nothing broke, and anyone checking would learn to ignore mismatches. In 0.6.0 the stories moved behind a resource template (worklore://story/{slug}), and resources/list became three fixed documents. Sidney's own verify.mjs, unmodified, now checks worklore in production: the Registry's hash equals the live one.
Reproduce this
Prerequisites: an MCP server you can call from a test (in-process or against a local URL), a test runner, and a version string the server reports in initialize (serverInfo.version). Optional: a listing in the official MCP Registry (https://registry.modelcontextprotocol.io) or another directory. Your agent will need from you: where the server's version is defined; how to call it from a test; whether it has auth (and a test token if it does); where you publish the listing. Steps:
- Write a test helper
surface()that, like a real client, callsinitialize,tools/list,resources/list,resources/templates/listandprompts/list, removesserverInfo.versionfrom theinitializeresult, and addsanswers_without_token: for each of those methods plusping, whether it returns a result with no credentials. - Hash it: SHA-256 of the JSON with sorted keys.
- Keep a committed lock file
{version, sha256, surface}. The test passes when the hash matches. When the hash differs and the version didn't change, fail with a message naming what changed and how to re-record. When both changed, fail until the lock is re-recorded (an environment flag likeUPDATE_MCP_SURFACE=1rewrites it). - Find the version you actually published: for the official Registry,
GET https://registry.modelcontextprotocol.io/v0/servers?search=<your server name>. Check out the commit that was live then, record the lock there, and copy it into today's code. - Run the test on today's code. If it fails, that's drift. Bump the version (and
server.json), re-record, deploy, and republish the listing. - Make it block something: run the suite in CI, or at the top of your deploy script.
- Before locking, look at what each list contains. If one changes by itself (records, stories, daily files), move those items behind a resource template or a tool, so the lists change only when you release.
- Publish the promise: compute the fingerprint in the shared
mcp-surface/1form (its §7 has a test vector to check your implementation against), put the block under_meta→io.modelcontextprotocol.registry/publisher-providedinserver.json, and republish.
Verify: change one sentence of the server's instructions without touching the version, and the test fails; revert and it passes. After republishing, the Registry's latest version equals serverInfo.version on the live server. node verify.mjs <name> <version> reports declared … ok.