Skip to main content

Versions and rollback

Every time you publish or delete a tool, the platform snapshots the server's whole tool set into a new numbered version, pinned to one exact container image. This page shows you how to list those versions, roll the server back to an earlier one, and retire a version you never want to return to.

Before you begin​

  • You need a project member role to list versions, and the project admin role to roll back, yank, or unyank.

  • You need an MCP server with at least two versions. If you do not have one, walk through publish tools and publish twice.

  • For the platformctl tabs: the CLI installed and platformctl login run. Nothing else — the CLI needs no endpoint set.

  • For the curl tabs: a token, your project id, and the server name in your shell. The examples also use jq.

    export CAI_API=https://api.codyhill.dev
    export CAI_TOKEN=$(curl -s "$CAI_API/v1/auth/login" \
      -d '{"email":"you@example.com","password":"your-password"}' | jq -r .token)
    export PROJ=$(curl -s -H "Authorization: Bearer $CAI_TOKEN" "$CAI_API/v1/projects" | jq -r '.projects[0].id')
    export SERVER=weather-tools

  • For the Console tab: a browser is enough. Everything on this page is under Compute → MCP servers.

What a version is​

A version is a frozen record of one successful build:

  • A number. Versions start at 1 and count up. Numbers are never reused.
  • An image digest. A digest is a fingerprint of the container image's exact contents, written like sha256:8c1f…. Change one byte of the image and the digest changes completely, so naming a digest names one specific image and no other. Version 2 today is byte-for-byte version 2 forever.
  • A tool-set snapshot. The tool names, plus every credential key any of those tools declared, as they stood at that moment.

Publishing a tool, updating a tool, and deleting a tool each create a new version, because each one changes the server's tool set as a whole. A version is created only when the build succeeds. A failed build leaves the version history untouched and puts the reason in the server's message field.

List the versions​

platformctl mcp versions weather-tools

You should see:

VERSION  CURRENT  YANKED  TOOLS  CREATED
3        yes      no      2      2026-08-12T14:11:07Z
2        no       no      1      2026-08-12T13:52:44Z
1        no       no      1      2026-08-12T13:40:19Z

Add -o json for the full record — the pinned image digest, the captured tool names, and the version's credential keys, all of which the table leaves out.

The list is newest first, and it is not split into pages. One request returns the server's whole history.

FieldTypeMeaning
versionintegerThe version number. Starts at 1, never reused.
image_digeststringThe fingerprint of the exact image this version runs. Omitted if none was recorded.
credential_keysarray of stringsThe project-secret names the tools in this version were allowed to read. Names only, never values.
tool_namesarray of stringsThe tools that existed when this version was built.
tool_countintegerHow many tools that was.
currentbooleantrue for the one version the server is running right now.
yankedbooleanPresent and true only when the version has been retired.
yanked_atstringWhen it was retired. Present only on yanked versions.
created_atstringWhen the version was built.

Both timestamps use RFC 3339, the standard format that looks like 2026-08-12T14:11:07Z. The Z means UTC.

Check which version is running​

Two places tell you the same thing. The versions list marks it with "current": true, and the server object carries it directly.

platformctl mcp get weather-tools

You should see:

created_at   2026-08-12T13:40:19Z
expose       -
image        ...@sha256:8c1f...
name         weather-tools
ready        true
state        ready
tool_count   2
tool_names   get_alerts, get_forecast
url          http://<private-hostname>
version      3
visibility   internal

Roll back to an earlier version​

Version 3 broke something. Point the server back at version 2.

platformctl mcp rollback weather-tools 2

You should see:

image        ...@sha256:41a9...
note         re-pointed the server at version 2's recorded image; no rebuild
rolled_back  true
server       weather-tools
version      2

What just happened, precisely:

  • The platform pointed the running server back at version 2's recorded image. Nothing was rebuilt, so a rollback is fast and cannot fail the way a build can.
  • The current version moved to 2. No new version number was created, because a rollback is not a publish.
  • The server keeps the same bearer token — it is not replaced. Agents and clients already holding it keep working. See connect agents and clients.
  • The action is recorded in your project's audit log as mcpserver.version.rollback.
Rolling back does not rewind your tool source

Rollback changes which image runs. It does not change the editable tool set you see at GET .../mcpservers/{name}/tools, which still holds the newest source you published.

So the moment you publish or delete a tool again, the platform builds a fresh version from that newest source — and the good version you rolled back to stops running. To make a rollback stick, publish the older source again as a new version.

Real error messages:

StatusMessageWhy
400version must be a positive integerThe version segment was not a whole number greater than zero.
404no such versionThis server has no version with that number.
409version 2 is yanked (retired); unyank it or publish a new version insteadThe target was retired. Unyank it first, or move forward instead.
409version 2 has no recorded image to roll back toThe version row exists but carries no image, so there is nothing to run.

Yank a version​

Yanking retires a version. The version stays in the history for the record, but the platform refuses to roll back to it. Use it when you know a version is bad — a leaked credential, or a tool that corrupts data — and you want to be sure nobody restores it by accident.

platformctl mcp yank weather-tools 3

You should see:

server   weather-tools
version  3
yanked   true

The version now shows up in the list with "yanked": true and a yanked_at timestamp. Yanking never deletes anything — the row, the digest, and the tool-set snapshot all survive.

You cannot yank the version the server is currently running:

{"error":"version 3 is the one the server currently runs; roll to another version before yanking it","request_id":"..."}

That is a 409. Roll back to a good version first, then yank the bad one.

Unyank a version​

Changed your mind, or the "known-bad" turned out to be a misdiagnosis.

platformctl mcp unyank weather-tools 3

You should see:

server   weather-tools
version  3
yanked   false

The version is a valid rollback target again. Yanking an unknown version, in either direction, returns 404 no such version.

Both actions are audited, as mcpserver.version.yank and mcpserver.version.unyank.

How the three actions are written in a URL​

Rollback, yank, and unyank do not each get their own path. You name the action by adding a colon and the action's name to the end of the version number in the URL:

POST /v1/projects/{projectID}/mcpservers/{name}/versions/{version}:rollback
POST /v1/projects/{projectID}/mcpservers/{name}/versions/{version}:yank
POST /v1/projects/{projectID}/mcpservers/{name}/versions/{version}:unyank

Anything else after the colon returns 404:

{"error":"unknown method on a version. The custom methods are POST .../versions/{version}:rollback, :yank and :unyank","request_id":"..."}

Summary​

ActionRequestRoleRebuilds?New version number?
Publish or delete a toolPUT / DELETE on .../tools/{tool}adminYesYes
List versionsGET .../versionsmemberNoNo
Roll backPOST .../versions/{version}:rollbackadminNoNo
YankPOST .../versions/{version}:yankadminNoNo
UnyankPOST .../versions/{version}:unyankadminNoNo

A quick checklist when something breaks in production, in whichever tab you have been using:

  1. List the versions and find the last one you know was good.
  2. Roll back to that number. The server is back within a rollout, with no build.
  3. Yank the broken version so nobody restores it.
  4. Fix the source and publish it, which mints a new version on top.

Next steps​