Updating & versioning
How versions work, which changes users have to consent to again, how updates reach users, and how to withdraw a bad version.
#Versions
version in plugin.json is semver: MAJOR.MINOR.PATCH, with an optional pre-release (1.3.0-beta.1).
- Every upload needs a new, greater version than any version of the app you've uploaded before — including rejected ones.
- Versions are immutable once uploaded. To change anything, bump the version.
- Use
CHANGELOG.mdto tell users what changed; it's shown with the update.
Your server is not versioned by the store — you deploy it whenever you like. That's the point of cloud apps: most fixes need no new version at all. You only publish a new version when the manifest or panel changes.
| Change | New version? |
|---|---|
| Fix a bug in your server | No — deploy your server |
| Change a tool's behaviour (same arguments) | No |
| Change a tool's input schema | No, but keep it backwards compatible (see below) |
Change a tool's description, add a tool | Yes |
Change the panel (ui/) or branding | Yes |
Add a grant, domain, account, scope or file param; change mcpUrl | Yes — human review and user consent |
#Keep your server compatible
Users update at their own pace, so your server is called by several app versions at once. Keep it working for every version that's still published:
- Add optional arguments, don't rename or remove required ones.
- Keep old tools until no published version declares them, then retire them.
- If you must break something, add a new tool id, ship a version that uses it, and remove the old tool later.
The app version isn't sent with calls, so design for overlap rather than branching on version.
#How updates reach users
Chataway checks the store for newer signed versions and offers the update. When an update asks for nothing new, it applies without asking.
When an update widens permissions — a new grant, domain, account, scope or file param, or a different mcpUrl — the app stays on its current permissions in each project until the user reviews the change. Until then, the app shows Needs consent and its new version's tools aren't active in that project. The user sees exactly what's new:
So: widen rarely, and explain every addition in permissions. Narrowing (removing a grant or domain) never needs consent.
#Pre-release testing
Test a new version in developer mode before you publish it: chataway dev runs your folder as a separate DEV app next to the store version. Point --mcp-url at a staging server to test server and app changes together.
#Yanking
If you published a version that shouldn't be used — it uploads to the wrong place, or leaks data — ask for it to be yanked from the developer dashboard, then publish a fixed version.
A yanked version is added to the signed revocation list. Every Mac checks the list hourly and at startup and disables the version: its tools are removed from chats and its panel closes, with a note to the user. When a fixed version is available, it's offered as an update.
The review team can also yank a version, with a reason sent to you — see the review guidelines.
#Revocation vs. disconnect
Yanking is about code you shipped. If instead you need to cut off a user's access — a leaked token, an abusive account — do it on your side: revoke the OAuth tokens on your server. Chataway will see 401s and ask the user to reconnect.