API versioning and deprecation

Each Hamster OSS surface carries its version where clients already look for one: MCP by protocol revision, the release catalog by schema_version, and the OpenAPI document by date.

MCP servers

Up to revision 2025-11-25, an MCP client and server agree on a protocol revision in the initialize handshake. From revision 2025-06-18 on, the client also sends that revision on every later HTTP request in the MCP-Protocol-Version header; 2024-11-05 and 2025-03-26 define no such header. If the server doesn't support the revision the client asks for, it answers with the latest one it does, and the client decides whether to continue. Revision 2026-07-28 drops the handshake: every request names its revision in its _meta and, over HTTP, in MCP-Protocol-Version. A server that doesn't support it answers 400 Bad Request with an UnsupportedProtocolVersionError listing the revisions it supports, and the client retries with a revision both support. See MCP versioning.

• Instance MCP server, https://<your-team>.tryhamster.dev/mcp — revisions 2024-11-05 through 2026-07-28.
• Hamster OSS account MCP server, https://tryhamster.dev/mcp — 2025-03-26, 2025-06-18 and 2025-11-25. An initialize request that asks for another revision gets 2025-11-25. A request whose MCP-Protocol-Version header names another revision gets 400 with the JSON-RPC error -32600, not an UnsupportedProtocolVersionError, so a client that tries 2026-07-28 first falls back to the initialize handshake.

A new tool or a new optional argument is not a breaking change. Removing a tool, or making an argument required, is one, and follows the deprecation steps below.

Release catalog

https://dl.tryhamster.dev/channels/tracks.json carries a schema_version, which is 1 today. Check it before you read the rest of the catalog.

OpenAPI document

info.version in the OpenAPI document is the date the document last changed.

Agent API and dashboard API

The agent API under https://tryhamster.dev/api/v1/agent and the dashboard's own API under https://tryhamster.dev/api/v1 carry their version in the path. The agent API accepts the OAuth bearer tokens described in Hamster OSS API; the dashboard's own API serves its pages and accepts browser sessions, not bearer tokens. The agent API sets Deprecation and Sunset on any operation that is being retired.

Deprecation and removal

How a deprecation is announced depends on what is going away.

• A whole HTTP resource, such as an endpoint: its responses carry a Deprecation header (RFC 9745) with the time it was deprecated, as a Unix timestamp such as Deprecation: @1798761600, and a Sunset header (RFC 8594) with the time it stops responding, as an HTTP date such as Sunset: Wed, 30 Jun 2027 00:00:00 GMT. The sunset is never earlier than the deprecation. A Link header with rel="deprecation" points to the notice. Both headers describe the resource as a whole, so they are not used for parts of it.
• An MCP tool, a tool argument or a field in a response or catalog: the page that documents it says it is deprecated and gives the date it stops working, and for a tool, its description says the same.

Either way, at least 90 days pass between the notice and the removal. That period is Hamster's own policy, not a requirement of any RFC. A security fix can move faster.

Nothing is deprecated today.