Versioning

How the MCP server is versioned, where to read the version, and what changes between releases.

The MCP server is a hosted service, so you always talk to the latest release. Versioning exists so you can tell what changed, and so tool names and inputs you built a workflow on do not move under you without warning.

Semantic versions

The server carries a semantic version, currently 1.6.0. What each part means for a client:

Bump	What it can contain	Example
Major (`2.0.0`)	A tool removed or renamed; a required input added; a compact response field removed; a move to a new REST API version	`get_track_count` folded into another tool
Minor (`1.6.0`)	New tools; new optional inputs; new fields in compact responses; new `/health` or `/tools` fields	five track-version tools added in 1.6.0
Patch (`1.4.1`)	Fixes, description wording, deployment changes with no visible surface change	Compact track serializer gains tag groups

Within a major version a tool you call today keeps its name, its inputs keep their names and types, and the fields in its compact response stay present.

Where to read the version

On initialize. Every MCP client receives the version in serverInfo, along with an instructions string that names the version, the REST API it targets and this policy. Clients that show server instructions to the model show this too.

{
  "serverInfo": { "name": "postal", "version": "1.6.0" },
  "instructions": "Postal MCP server 1.6.0 (REST API v1). Tool names and input schemas are stable within a major version; …"
}

Health endpoint. No authentication.

curl https://mcp.postal.music/health

{ "status": "ok", "service": "postal-mcp", "version": "1.6.0", "apiVersion": "v1" }

Tool catalog. The same fields precede the list of tools.

curl https://mcp.postal.music/tools

{ "version": "1.6.0", "apiVersion": "v1", "count": 39, "tools": [ … ] }

apiVersion is the REST API version the tools are written against. A change there is always a major release of the server.

Deprecated tools

MCP has no built-in deprecation flag, so a tool being retired says so in its description:

[Deprecated — removed in 2.0.0, use get_library_stats instead] Get the total number of tracks in your library

A deprecated tool keeps working exactly as before. It stays for at least one minor release before the major version that removes it, and both the deprecation and the removal are listed in the changelog. Prefer the named replacement as soon as you see the prefix; assistants reading the catalog are told the same in the server instructions.

Full responses follow the REST contract

Read tools return compact objects by default (see Compact mode). Fields in compact objects are governed by the server version above. Passing detail: "full" returns the REST API's own payload, which is governed by the REST versioning rules instead: fields are only ever added within /api/v1.

Protocol versions

The server speaks the Model Context Protocol through the official TypeScript SDK and negotiates the protocol version with each client on initialize. It currently accepts 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05 and 2024-10-07. Dropping an old protocol version is a minor release, since maintained clients always negotiate the newest one they share with the server.

Pinning

There is no way to pin the hosted server to an older release. If a workflow needs a surface that does not move at all, call the REST API directly: /api/v1 is frozen by contract, the MCP server is not.