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.
There is no public API hostname yet in this alpha. Use the endpoint your administrator gives you, or a port-forward. platformctl has no MCP commands yet either — use the API or the console.

export CAI_API=http://localhost:8080   # your admin-provided endpoint or port-forward
export TOK=$(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 $TOK" "$CAI_API/v1/projects" | jq -r '.projects[0].id')
export SERVER=weather-tools

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. The exact container image that build produced, pinned by content hash. Version 2 today is byte-for-byte version 2 forever.
A tool-set snapshot. The tool names and the union of credential keys that were published at that moment.

Publishing a tool, updating a tool, or deleting a tool all mint 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

curl -s "$CAI_API/v1/projects/$PROJ/mcpservers/$SERVER/versions" \
  -H "Authorization: Bearer $TOK" | jq .

You should see:

{
  "server": "weather-tools",
  "versions": [
    {
      "version": 3,
      "image_digest": "...@sha256:8c1f...",
      "credential_keys": ["weather-api-key"],
      "tool_names": ["get_alerts", "get_forecast"],
      "tool_count": 2,
      "current": true,
      "created_at": "2026-08-12T14:11:07Z"
    },
    {
      "version": 2,
      "image_digest": "...@sha256:41a9...",
      "credential_keys": ["weather-api-key"],
      "tool_names": ["get_forecast"],
      "tool_count": 1,
      "current": false,
      "created_at": "2026-08-12T13:52:44Z"
    },
    {
      "version": 1,
      "image_digest": "...@sha256:07e3...",
      "credential_keys": [],
      "tool_names": ["get_forecast"],
      "tool_count": 1,
      "current": false,
      "created_at": "2026-08-12T13:40:19Z"
    }
  ]
}

The list is newest first, and it is not paginated — one request returns the server's whole history.

Field	Type	Meaning
`version`	integer	The version number. Starts at 1, never reused.
`image_digest`	string	The exact image this version runs, pinned by content hash. Omitted if none was recorded.
`credential_keys`	array of strings	The project-secret names the tools in this version were allowed to read. Names only, never values.
`tool_names`	array of strings	The tools that existed when this version was built.
`tool_count`	integer	How many tools that was.
`current`	boolean	`true` for the one version the server is running right now.
`yanked`	boolean	Present and `true` only when the version has been retired.
`yanked_at`	string	When it was retired (RFC 3339). Present only on yanked versions.
`created_at`	string	When the version was built (RFC 3339).

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:

curl -s "$CAI_API/v1/projects/$PROJ/mcpservers/$SERVER" \
  -H "Authorization: Bearer $TOK" | jq '.mcp_server | {status, version, image}'

You should see:

{
  "status": "ready",
  "version": 3,
  "image": "...@sha256:8c1f..."
}

Roll back to an earlier version

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

curl -s -X POST "$CAI_API/v1/projects/$PROJ/mcpservers/$SERVER/versions/2:rollback" \
  -H "Authorization: Bearer $TOK"

You should see:

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

What just happened, precisely:

The platform re-pointed the running server 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 — a rollback is not a publish.
The server's per-server bearer token is reused, not rotated, so 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 — that still holds the newest source you published. The moment you publish or delete a tool again, the platform builds a fresh version from that source, and the fix you rolled back to disappears from the running server. To make a rollback stick, publish the older source again as a new version.

Real error messages:

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

Yank a version

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

curl -s -X POST "$CAI_API/v1/projects/$PROJ/mcpservers/$SERVER/versions/3:yank" \
  -H "Authorization: Bearer $TOK"

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:

curl -s -X POST "$CAI_API/v1/projects/$PROJ/mcpservers/$SERVER/versions/3:unyank" \
  -H "Authorization: Bearer $TOK"

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.

The three custom methods

Rollback, yank, and unyank are not separate paths — they are a colon-suffixed method appended to 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":"..."}

In the console

Open Compute → MCP servers, pick a server, and use the versions table: each row shows the version number, its tools, its credential keys, and when it was built, with buttons to roll back, yank, or unyank. The current version is marked and offers no rollback button, because rolling back to what is already running does nothing.

Summary

Action	Request	Role	Rebuilds?	New version number?
Publish or delete a tool	`PUT` / `DELETE` on `.../tools/{tool}`	admin	Yes	Yes
List versions	`GET .../versions`	member	No	No
Roll back	`POST .../versions/{version}:rollback`	admin	No	No
Yank	`POST .../versions/{version}:yank`	admin	No	No
Unyank	`POST .../versions/{version}:unyank`	admin	No	No

A quick checklist when something breaks in production:

GET .../versions and find the last version marked good.
POST .../versions/{version}:rollback to that number. The server is back within a rollout, with no build.
POST .../versions/{version}:yank on the broken version so nobody restores it.
Fix the source and publish it, which mints a new version on top.

Next steps

Connect agents and clients — the endpoint URL and the per-server bearer token.
Publish tools — how each publish mints the versions you just rolled between.
MCP servers API reference — every field, status code, and error string.
Tutorial: weather tools over MCP — the end-to-end walkthrough.

Before you begin​

What a version is​

List the versions​

Check which version is running​

Roll back to an earlier version​

Yank a version​

Unyank a version​

The three custom methods​

In the console​

Summary​

Next steps​

Before you begin

What a version is

List the versions

Check which version is running

Roll back to an earlier version

Yank a version

Unyank a version

The three custom methods

In the console

Summary

Next steps