Versioning
Build Against a Stable Contract
See which MCP protocol versions Archie speaks, track every change to the tool catalog, and read how we handle breaking changes before they reach you. Additive changes ship continuously. Breaking changes are rare, dated, and announced.
MCP Protocol Versions
The MCP server negotiates the protocol version on connect. Archie speaks the following revisions; a client offers the newest it supports and the server agrees on the highest both share.
| Version | Status |
|---|---|
2025-11-25 | Current. The default for new connections. |
2025-06-18 | Supported. Negotiated for older clients. |
You do not pin the MCP version yourself; the client handles negotiation. If a client offers only a version Archie no longer speaks, the connection is refused with a clear protocol error rather than a silent downgrade.
REST API Versions
The REST surface is dated. Pin a version with the Archie-Version header. Omit it and the call uses the latest. Pinning means a deploy never changes a response shape under you.
curl https://api.dev.arch.ie/api/v1/skills/workstream.list/invoke \
-H "Authorization: Bearer $ARCHIE_API_KEY" \
-H "Archie-Version: 2026-04-24"What Counts as Breaking
We treat the following as breaking, and never ship them silently:
- Removing or renaming a field, tool, scope, or endpoint.
- Changing the type or meaning of an existing field.
- Adding a new required request field.
- Tightening validation so a previously accepted request now fails.
These are additive and ship continuously, with no version bump:
- A new tool, endpoint, scope, or optional request field.
- A new field on a response.
- A new enum value on a field documented as open.
Tool-Catalog Changes
The tool catalog mirrors the live registry, so it is always current. When a tool ships, changes its annotation, or is deprecated, it lands in the changelog with a date. The OpenAPI spec at /openapi.json regenerates with it, so generated clients stay in step.
A deprecated tool keeps working through its announced window and carries a deprecation note in the catalog pointing at its replacement.