# Versioning and deprecation policy

How the agent-facing surface of That SEO Agent changes, and what you are owed
before it does. This document covers the MCP endpoint at `https://thatseoagent.com/mcp`, the
discovery documents under `/.well-known`, and the markdown representations at
the site root.

## Versioning is by protocol revision, not by URL

`/mcp` is a stable address and will not move. There is no `/v1/` and there will
not be one: moving the path would break every connected client, and the thing
that actually changes is the protocol, not the location.

Send the `MCP-Protocol-Version` header to pin the revision your integration was
written against. The transport validates it against the revisions this server
supports and answers **400** on one it does not, rather than silently serving you
something else. Omit the header and the server uses the revision negotiated
during `initialize`.

Read the supported set from the `initialize` result rather than hardcoding it.
It moves when the SDK moves, and a copy in your code starts lying at our next
upgrade for the same reason a copy in our OpenAPI spec would.

The discovery documents carry their own version inside the payload:
`specVersion` for the AI catalog, `$schema` for the agent-skills index and the
MCP server card.

## What counts as a breaking change

- Removing a tool, or removing a parameter from one.
- Making an optional parameter required.
- Changing the meaning of a field without changing its name.
- Changing the transport or the authentication scheme.

Adding a tool, adding an optional parameter, and adding a field to a response are
**not** breaking. Write clients that tolerate unknown fields.

## What we do before a breaking change

1. **The tool says so first.** A tool on its way out keeps working and its own
   description states that it is deprecated and what to call instead. Since your
   client reads descriptions from `tools/list` at connection time, you get the
   notice through the same channel you already use, without polling anything.
2. **The `Deprecation` and `Sunset` headers appear then, and not before.** When
   a resource is genuinely deprecated, its responses carry the IETF
   `Deprecation` header, and `Sunset` (RFC 8594) once a removal date exists.
   They are absent today because nothing is deprecated today. Their absence is
   information, which is exactly why we do not emit them speculatively.
3. **Never removed in the release that deprecates it.** Deprecation and removal
   are two separate changes, and the second one waits.
4. **The server card is the authority on what exists.**
   `https://thatseoagent.com/.well-known/mcp/server-card.json` generates its `tools` array from
   the live registry, so it cannot describe a tool the server does not have, or
   omit one it does. If this document and the server card ever disagree about
   what exists, the server card is right.

## Rate limits

The MCP endpoint allows **120 tool calls per
60 seconds, per account** — shared across every tool and
every connected client, so reconnecting or switching tools does not clear it.

Every response states the policy in a `RateLimit-Policy` header, including the
401 you get without a credential. A successful call also carries `RateLimit`
with your remaining budget and the seconds until it resets. An unauthenticated
response carries no remainder, because the budget is per account and a refused
request has no account.

Exceeding the limit does not produce a 429. It produces a normal MCP tool result
marked as an error, whose text says how long to wait — no shipped MCP SDK
recognises a 429, so a 429 would never reach the model that needs to read it.

## Errors

Refusals are RFC 9457 `application/problem+json`, carrying `code`,
`resolution` and `documentation_url` alongside the standard fields. `code` is
the stable part; branch on it rather than on `detail`, which is prose and may be
reworded.

## Where to look next

- OpenAPI description: https://thatseoagent.com/openapi.json
- MCP server card: https://thatseoagent.com/.well-known/mcp/server-card.json
- How to get credentials: https://thatseoagent.com/auth.md
- Documentation index: https://thatseoagent.com/en/docs
- Contact: support@thatseoagent.com