Package versioning

A Metabind project’s package is the immutable bundle of components published as a unit. Each publish produces a new version. This guide explains what version numbers mean and how Types stay stable across them.

​

Semantic versioning

Metabind packages follow semantic versioning — MAJOR.MINOR.PATCH: MCP App Studio suggests the right bump in the publish dialog based on a diff scan, but the suggestion can be overridden. When in doubt, prefer the higher bump — a misclassified breaking change as a minor version causes silent failures on connected hosts.

​

How Types pin to versions

When a Type is published, it pins to the package version that was current at publish time: After the next publish to 2.5.0, the production endpoint serves the new package — but a Type unchanged in this publish still functionally references 2.4.0 semantics because its schema and rendering logic are identical in both. Versioning is per-package, not per-Type, so all Types from the same publish share the version. This means: if a project publishes 2.5.0 and only changes one component, the other tools’ behavior doesn’t drift. Their bundled code is still byte-for-byte the same — the version label changed, the artifact didn’t.

​

What’s pinned, what’s not

The right column lists things that connected hosts pick up at request time, not bundle time. You can rotate a secret or sharpen a tool description without republishing.

​

When to bump major

A new major version is a signal to consumers that they should re-test against your tools. Major bumps make sense when:

• A required property is removed or renamed.
• An enum value is dropped.
• A component is removed.
• The shape of a Data Tool’s output changes incompatibly.
• A component’s behavior changes in a way that AI prompts may need to adjust to (e.g., a card now expects a caption where before it inferred one from title).

If the change is genuinely new behavior, prefer adding a new component rather than mutating an existing one. ProductCard and ProductCardV2 can coexist; the project palette decides which is in use.

​

When minor is enough

Minor is the right call for additive changes:

• New components added to the project palette.
• New optional properties on existing components.
• New Types added to the project.
• Improvements that are backward-compatible by construction.

In practice, most publishes are minor. A long-lived project might sit at 15.4.0 after a year of incremental additions.

​

When patch is enough

Patch is for changes that don’t touch the schema or shape:

• Layout polish (padding, color, typography).
• Typo fixes in user-visible strings.
• Bug fixes inside Data Tool handlers.
• Performance improvements.

A publish that touches only patches can be promoted to production with low risk.

​

Versions and connected hosts

Connected MCP hosts list tools and cache schemas. When a host reconnects after a publish:

• Patch update: schemas are byte-identical; the host’s cache stays valid (no re-list needed in some hosts).
• Minor update: new tools/properties appear; existing ones unchanged. The host re-lists, picks up additions.
• Major update: existing tools have changed shape; the host’s cached schemas are now wrong until it re-lists.

Because hosts re-list on most conversation starts anyway, the rollout is smooth in practice. The version label is mostly a signal to humans — your team, partners, customers — about the magnitude of the change.

​

Looking up the current version

In MCP App Studio, the project header shows the currently published version next to the Publish button. Click it to see the full publish history. For programmatic access, the production endpoint exposes the package version in its capabilities response — see REST API: project info.

​

Pre-release versions

MCP App Studio doesn’t expose pre-release labels (2.5.0-beta.1) in MVP. Use draft for any pre-release exposure: connect a small group of users to the draft endpoint, gather feedback, then publish.

​

Long-term versioning practices

A few patterns from teams that have shipped many versions:

• Don’t bump major casually. A major bump asks every consumer to re-evaluate. Only do it when something has actually broken.
• Group related changes into one publish. Publishing 5 versions in an hour is noisy — group the small changes into one and bump.
• Write changelog notes that mention impact. “Renamed headline → title. AI prompts that referenced the old property name will need to be updated.” beats “Renamed property.”
• Keep a public changelog if you have external consumers. The publish notes are the input to that changelog.

​

Related