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.8.0. The tools themselves are not defined on the server: it serves the catalog the REST API publishes at GET /api/v1/mcp/manifest, so a new or changed tool ships with the API and shows up on the next catalog refresh without a server release. The tool reference is generated from that catalog and names the manifest version and API version it was taken from (manifest version 2, REST API v1, as of 2026-10-06).

What each part of the server version 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.8.0`)	New tools; new optional inputs; new fields in compact responses; new `/health` or `/tools` fields	tools served from the API's manifest in 1.8.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, the catalog the tools come from and this policy. Clients that show server instructions to the model show this too.

{
  "serverInfo": { "name": "postal", "version": "1.8.0" },
  "instructions": "Postal MCP server 1.8.0 (REST API v1). Tool catalog: 39 tools from Postal API build ca14061… (manifest v2). 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.8.0",
  "apiVersion": "v1",
  "manifest": { "status": "ok", "version": 2, "build": "ca14061…", "generatedAt": "2026-10-06T09:49:43.999Z", "tools": 39, "ageSeconds": 0 }
}

manifest describes the catalog the server is currently serving: the manifest version, the API build that produced it, when it was generated and how many tools it holds. ageSeconds is how long ago the server last fetched it from the API.

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

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

{ "version": "1.8.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. The catalog itself is a copy of GET https://api.postal.music/api/v1/mcp/manifest, which the server refreshes on a schedule and keeps a last-good copy of, so a short API outage does not empty the tool list.

Deprecated tools

MCP has no built-in deprecation flag, so a tool being retired says so in its description. The prefix names the removal date when one is set, followed by the note from the catalog, which names the replacement:

[Deprecated — removed after 2027-01-01] Use get_library_stats instead. Get the total number of tracks in your library

The same deprecation is a structured deprecation object on the tool in the manifest (since, sunset, successor, note), and the tool reference shows it as a warning above the tool's parameters. 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.