## TL;DR
Version the server with semver, write the changelog as you go, and update every registry listing in the same release you ship. Listings rot fast because registries do not watch your repo; a tool you renamed three releases ago is still advertised until you push the update. Make the listing update a release checklist item and the drift stops.

```text
versioning and updating MCP registry listings
```

## Use this when
- You are shipping a new version of an MCP server
- A tool was renamed, removed, or changed its inputs
- Your registry listing shows tools the server no longer has
- You need to deprecate a server or hand it to a new maintainer
- Reviewers flagged listing drift on a resubmission

## Not for this skill when
- This is the first submission (use the submission and testing guides)
- The question is about the MCP protocol version negotiation itself
- You are versioning a plain API or CLI, not an MCP server
- You need to migrate agents off a tool with zero breakage (that is a migration plan, bigger than versioning)

## Steps
1. Adopt semver for the server and mean it. Major for removed or renamed tools and changed input schemas, minor for new tools, patch for bug fixes. Agents pin versions, so a casual breaking change in a minor release breaks strangers.
   ```text
   major: tool removed/renamed, inputs changed incompatibly
   minor: new tool added, optional inputs added
   patch: bug fix, description clarifications
   ```
   Expected output: a versioning rule written down where contributors see it. Success check: the last three releases each map cleanly to one of the three rows.

2. Keep a changelog that an agent operator can skim. One line per change, grouped by version, with tool names spelled exactly as agents call them. "Improved stability" helps nobody; "list_prs now accepts a state filter" does.
   ```text
   ## 2.1.0
   - added search_issues tool (owner, repo, query)
   - list_prs: new optional state filter
   ```
   Expected output: a changelog file at the repo root, current to this release. Success check: a user can answer "what changed between 2.0 and 2.1" in under a minute.

3. Update every registry listing in the same release motion. Bump the version field, sync the tools list, and refresh the description if tools changed. Do it the day you release; "next week" becomes "three versions from now".
   ```text
   [ ] registry A: version bumped, tools list synced
   [ ] registry B: version bumped, tools list synced
   [ ] registry C: version bumped, tools list synced
   ```
   Expected output: all listings show the new version and tool set. Success check: spot-check one listing as a stranger and confirm it matches the running server.

4. Handle removals with a deprecation window, not a disappearance. Mark the tool deprecated in the description for one minor release, log a warning when it is called, then remove it in the next major. Agents cannot read your mind, but they can read a deprecation notice.
   ```text
   [ ] deprecated tool flagged in its description
   [ ] warning logged on each call during the window
   [ ] removal lands in a major version with a changelog entry
   ```
   Expected output: zero surprise breakages. Success check: no agent-visible tool vanishes without one release of warning.

5. Decide what "old versions" means for your listing. Some registries show only the latest; some keep history. If old versions stay installable, say so in the listing ("1.x still available for pinned agents"); if not, say that instead. Ambiguity here strands agents on dead versions.
   ```text
   old-version policy: [kept installable | latest only | supported for N months]
   ```
   Expected output: a stated policy, visible on the listing. Success check: you can answer "can I still install 1.4" without checking.

## Variant phrasings
### How to update an MCP server listing after a release
Release-day phrasing. Step 3 is the whole answer: same-day listing sync across every registry, verified as a stranger.

### MCP server semver best practices
Versioning phrasing. Steps 1 and 2: strict semver plus a changelog written for agent operators.

### Deprecating an MCP tool without breaking agents
Migration phrasing. Step 4 expanded: deprecation window, call-time warnings, removal in a major.

### My registry listing is out of date, how to fix it
Cleanup phrasing. Audit the listing against the running server, then follow step 3; add step 5 so it does not happen again.

## Why it happens
Registries are snapshots, not live views. Nothing notifies a registry when your repo ships; the listing is a form you filled in once. Every release widens the gap between the snapshot and reality unless updating the snapshot is part of the release itself. Drift is the default, accuracy is the habit.

## Edge cases / pitfalls
- A registry that caches aggressively can show the old listing for days after you update. Note the cache behavior per registry so you do not "fix" the same listing twice.
- Renaming a tool is a removal plus an addition. Treat it as breaking even if the new tool does the same thing; agents call names, not intentions.
- If you transfer the repo to a new org, most registries need the listing ownership transferred separately. The code moved; the listing did not follow automatically.
- Beta or experimental tools in a listing attract real usage. Mark them clearly or leave them out until they are stable; "beta" in the description is a promise agents will ignore.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_zUkwWksWvzxQIq9M3uFqCg