Publish, list versions and roll back: an assistant's lifecycle from the MCP

You're editing an assistant from your agent, and at that same moment a customer writes on WhatsApp. Which one answers: what you just changed, or yesterday's version?

In CognitionDesk an assistant has two states, and knowing which one runs on each channel is what lets you edit without fear. With @cognitiondesk/mcp the whole cycle runs from Claude or any other MCP client with four tools: try_assistant, publish_assistant, list_assistant_versions and rollback_assistant.

Draft and published: who runs what

• The draft is the live document: what update_assistant writes and what get_assistant returns. The dashboard chat and try_assistant run it, so you see your edits immediately.
• The published version is a frozen copy made by publish_assistant. It's what your customers get: the widget embedded in a site, the SDK, every turn that comes in through an API key, and WhatsApp.

The practical consequence is just one: update_assistant changes nothing for any customer until you publish.

One case is worth knowing: an assistant that was never published runs its draft live, with no protection and nothing to go back to. The first publish is the moment it becomes safe to edit.

1. Before you touch it: what's live

list_assistant_versions returns the published versions, newest first, and which one is live. It needs the assistants:read scope. The shape of the response:

{
  "publishedVersionId": "<v3 id>",
  "enVivo": "v3",
  "total": 3,
  "aviso": null,
  "versiones": [
    { "versionId": "<v3 id>", "numero": "v3", "enVivo": true,  "publishedAt": "…", "publishedBy": "…" },
    { "versionId": "<v2 id>", "numero": "v2", "enVivo": false, "publishedAt": "…", "publishedBy": "…" },
    { "versionId": "<v1 id>", "numero": "v1", "enVivo": false, "publishedAt": "…", "publishedBy": "…" }
  ]
}

(The field names are in Spanish: enVivo is "live", aviso is "warning".) If the assistant was never published, total is 0 and aviso says so in plain words: the customers are getting the draft live and there is nothing to roll back to. It's not an empty list you skim past.

The list doesn't repeat each version's prompt — that's what get_assistant is for. It's there so you can read at a glance what's live and what you can go back to.

2. Edit and try the draft

update_assistant changes the draft. try_assistant talks to it through the same code path that serves customers, so what it answers there is what they will get. Test with messages, not a single message: most failures show up on the second turn, when the assistant has to remember what was already said.

Each try_assistant call runs the model and spends the account's credits; it isn't recorded as a real conversation.

3. Publish

publish_assistant freezes the draft as a new version and points the live bot at it. It returns the versionId. From that moment it talks to real customers, so the rule worth giving your agent is: publish only with the assistant owner's OK, after showing them what it answered in the test.

4. Roll back

If a publish went wrong in front of customers, rollback_assistant points the live bot at an earlier version. It needs the assistants:write scope and a versionId taken from list_assistant_versions — never guessed.

Rolling back does not touch the draft: your latest edits are still there. You fix them, try again with try_assistant, and publish again.

Measured against production on September 23, list_assistant_versions answered in 2.5 s and rollback_assistant in 2.1 s. Undoing a bad publish takes seconds, not rebuilding a prompt from memory.

The order, in one line

For an assistant that already serves customers: list_assistant_versions (know what you're replacing) → update_assistant (draft) → try_assistant (draft) → show it to the owner → publish_assistant on their OK → if it goes wrong, rollback_assistant.

It's in @cognitiondesk/mcp and in the MCP guide. If you run assistants from your agent and want to review your publishing flow, get in touch.