--- title: "API versioning and deprecation" description: "How Hamster OSS versions its MCP servers, release catalog and OpenAPI document, and how it announces a change that breaks clients." canonical: "https://tryhamster.dev/docs/api-versioning" last-updated: "2026-11-05" --- # API versioning and deprecation > How Hamster OSS versions its MCP servers, release catalog and OpenAPI document, and how it announces a change that breaks clients. *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](https://modelcontextprotocol.io/specification/2026-07-28/basic/versioning). - Instance MCP server, `https://.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](https://tryhamster.dev/openapi.json) 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](https://tryhamster.dev/developers); 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](https://www.rfc-editor.org/rfc/rfc9745)) with the time it was deprecated, as a Unix timestamp such as `Deprecation: @1798761600`, and a `Sunset` header ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)) 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.