Versioning & deprecation#

The MCP public API is versioned to give integrators a stable contract. Version lives in the server path/version, not in tool names.

Version scheme#

Surface	Scheme	Example
MCP server	Major version in the server path	`mcp.qaqnuz.uz/v1` (a.k.a. `/mcp/v1`)
Individual tools	A stability tier in the tool description	`[stable]`, `[beta]`, `[deprecated]`

The current major version is v1. The server identifies itself as qaqnuz-mcp v1.0.0.

The mcp.qaqnuz.uz/v1 HTTP endpoint is the designed public path, but the HTTP/SSE gateway is not yet deployed (it rides platform GATE-5 infrastructure). v1 ships today over the stdio transport; the version contract on this page applies to both transports.

Stability tiers#

Each tool advertises a stability tier as a prefix on its description:

stable — production-ready. Changes only via the breaking-change process

below. Pin production integrations to stable tools.

beta — may change additively (new optional fields, new tools) without

a server-version bump, but is labelled so you can avoid depending on it in production.

deprecated — slated for removal. Keeps working for the full deprecation

window (below). Migrate off it.

A tool with no prefix is treated as stable.

Change classification#

Change	Version impact
Additive — a new field, a new tool, a new `beta` tool	No version bump; recorded in the changelog.
Breaking — removing a field, changing semantics, removing a `stable` tool	A new major server version (e.g. `/mcp/v2`) is mandatory.

Deprecation policy#

When a stable capability must be removed:

Announce the deprecation (changelog entry + customer notification in

uz / ru / en).

Run in parallel for at least 6 months — the deprecated capability keeps

working throughout.

Remove it, with a final changelog entry.

A deprecated-tier tool keeps functioning for the entire parallel-operation window, so you always have time to migrate.

Changelog#

API changes are recorded in the project's API changelog on every release. Breaking changes are additionally called out as part of the release checklist. There are no breaking changes in v1 to date.

Practical guidance#

Pin to stable. Treat beta as preview-only for production paths.
Re-discover periodically. Re-run list_tools so you

notice new tools and tier changes (e.g. a tool moving beta → stable, or stable → deprecated).

Watch for /mcp/v2. A new major version only appears for breaking changes;

v1 continues under the deprecation policy when that happens.