Manage app versions with the ConvertSite MCP

The ConvertSite MCP gives your connected assistant three tools for app versions: List app versions lists the saved versions of an app, Compare app versions shows what changed between two of them, and Restore an app version puts the app's draft back to an earlier version. Listing and comparing are read-only. Restoring is a write: it replaces the draft's pages, blocks, theme variables, and stylesets, and it never publishes. Your live site keeps running the version you published until you publish again.

What you need

Connect Claude or Codex to ConvertSite first. Listing and comparing need the read scope the standard connection grants (convert:apps.read). Restoring needs write access (convert:apps.write), which the same standard connection grants, plus an open app session: your assistant calls open_app and passes the session token it gets back to the restore tool.

New to the connection? See Connect ConvertSite MCP to Claude or Connect ConvertSite MCP to Codex.

App versions and table versions are different

App versions snapshot the whole app: its pages, blocks, theme variables, and stylesets. Table versions snapshot one table. The two histories are separate, so use the table restore to roll back table data. See Restore a previous version of a table.

List app versions

List app versions (list_versions) returns the saved versions of one app, newest first. Versions are saved when the app is published, when the built-in assistant changes it, when a connected tool changes it (Claude, Codex, or another MCP client), and as autosaves.

Input	Required	What it is
`app_id`	Yes	The app to list versions for.
`limit`	No	How many versions to return. Defaults to 20, maximum 100.

Each version in the response has these fields:

Field	What it contains
`id`	The version's id. This is the value your assistant passes to the compare and restore tools.
`source`	What created the version: `Publish`, `Assistant`, `Claude`, `Codex`, `Mcp`, or `Autosave`.
`description`	An optional note about the version.
`created_at`	When the version was saved, as an RFC 3339 timestamp.
`is_current`	Whether this version is the app's current state.

Compare app versions

Compare app versions (compare_versions) reports what changed between two versions of an app before you decide to restore. Each side of the comparison can be a version id from list_versions or "current", the app as it is now. from is the earlier side and to the later, so a diff from an old version to "current" shows everything added since.

Input	Required	What it is
`app_id`	Yes	The app to compare versions for.
`from`	Yes	The earlier side: a version id or `"current"`.
`to`	No	The later side: a version id or `"current"`. Defaults to `"current"`.
`page`	No	A page path to narrow the comparison to one page.

The response reports added, removed, and changed items in four categories: pages, blocks, theme_variables, and stylesets. Each changed item carries a unified diff: page and block content exactly as the Read tool returns it, theme variables and stylesets as JSON. A truncated flag is true when the comparison hit its 400-line diff cap and cut or omitted lines.

How items match across versions

The comparison matches items between the two sides by stable identity, not by raw id alone:

Pages match by id.
Blocks match by name, and repeated names are numbered.
Theme variables and stylesets match by key.

Restoring re-mints component and block ids, so an id that exists on only one side shows as ... in the diff. Ids present on both sides stay, so a link that moved between pages still shows up.

Compare errors

Error message	Cause
`"{value}" is neither "current" nor a version id from list_versions.`	One side was given a value that is neither `"current"` nor a version id. Fix the value.
`This app has no version {version_id}. Call list_versions.`	The version id does not belong to this app. Call `list_versions` to get valid ids.
Neither side has a page at `{page}`. Call list_pages for the paths.	The page filter matches no page on either side. Call `list_pages` for the correct paths.

Restore an app version

Restore an app version (restore_version) replaces the app's draft with the content of an earlier version. It needs the session token of an open app session and an explicit confirm: true. Without confirmation, the tool refuses and returns: Restoring replaces this app's pages, blocks, theme variables and stylesets with the version's. Ask the user to confirm, then call again with confirm: true. This is by design: your assistant must ask you before restoring, and you decide.

A restore changes the draft only. The response always returns published: false, and your live site keeps running the published version until you publish again.

The restore takes the session's write slot like every MCP write: changes are applied one call at a time, so another write sent alongside cannot interleave with the restore.

Inputs

Input	Required	What it is
`app_id`	Yes	The app to restore a version for.
`version_id`	Yes	The version to restore, from `list_versions`.
`session_token`	Yes	The token of an open app session, from `open_app`.
`confirm`	Yes	Set to `true` after you have agreed to the restore. Defaults to `false`.

What a restore replaces and what it does not

Restored	Not restored
Pages	Shared blocks
Blocks	Workspace theme settings
App theme variables	Tables
Stylesets	Fonts and uploaded assets
	App settings
	The live published site

The response returns the restored version id, counts of what was restored (pages, blocks, theme variables, stylesets), an undo_version_id, a not_restored list naming the content the restore left alone, and published: false.

The undo version

When the app has changes no saved version captures yet, the restore first saves the content being replaced as an undo version, labeled Autosave, and returns its id as undo_version_id. When everything is already captured by a version, no undo version is created and undo_version_id is null. The undo version appears in list_versions like any other version, so your assistant can compare against it or restore it to undo the restore.

Restore errors

Error message	Cause
`Restoring replaces this app's pages, blocks, theme variables and stylesets with the version's. Ask the user to confirm, then call again with confirm: true.`	The call was made without `confirm: true`. This is the expected first step: your assistant asks you, you agree, and it calls again with `confirm: true`.
`This app has no version {version_id}. Call list_versions.`	The version id does not belong to this app. Call `list_versions` to get valid ids.
`This app's write session is no longer held — another editor took over, or it expired. Call open_app again and re-read the app before making further changes; anything read earlier may be out of date.`	The session token no longer holds the write slot: another editor took over or the session expired. Open the app again and re-read it before making further changes.
`Another change to this app is still being applied. Change an app one call at a time: wait for the previous call to return, then retry this one.`	Another write is still in progress. Wait for it to return, then retry.
`This version has no pages, so it can't be restored.`	The version contains no pages. Pick a different version.

Example: roll back a bad change

A typical round trip in plain language: "List the versions of my app, compare the last one to current, and tell me what changed." You read the diff, decide to go back, and say: "Restore that version." Your assistant calls open_app, asks you to confirm, calls restore_version with confirm: true, and reports the counts and the undo version id. Your draft is back to the earlier version; publish when you want the live site to match.

Was this helpful?