Agent Wranglers

AGT-35Recommended

Answer an unsupported protocol version with the versions you serve

Implement server/discover. Answer a request in a protocol version you do not serve with error -32022 that lists the versions you serve. Answer a legacy initialize with an error that names them too.

By Agent Wranglers. Updated .

Spec version

MCP 2026-07-28

Review by

2027-04-30

How to do it

A client picks a version from your list and retries, so a clear error keeps agents working through an upgrade. Older clients have no way to move forward on their own, and the error text may be all their user sees. The 2026-07-28 revision deprecated Roots, Sampling, Logging and Dynamic Client Registration. Each deprecated feature stays for at least twelve months, so plan the move off them now. Register clients as Register MCP clients with Client ID Metadata Documents says.

Examples

JavaScript example

const SUPPORTED_VERSIONS = ['2026-07-28', '2025-11-25'];
const UNSUPPORTED_PROTOCOL_VERSION = -32022;

export function versionError(id, requested) {
  if (SUPPORTED_VERSIONS.includes(requested)) return null;
  return { jsonrpc: '2.0', id, error: { code: UNSUPPORTED_PROTOCOL_VERSION, message: 'Unsupported protocol version', data: { supported: SUPPORTED_VERSIONS, requested } } };
}

Python example

SUPPORTED_VERSIONS = ["2026-07-28", "2025-11-25"]
UNSUPPORTED_PROTOCOL_VERSION = -32022

def version_error(request_id: int, requested: str) -> dict | None:
    if requested in SUPPORTED_VERSIONS:
        return None
    return {"jsonrpc": "2.0", "id": request_id, "error": {"code": UNSUPPORTED_PROTOCOL_VERSION,
            "message": "Unsupported protocol version", "data": {"supported": SUPPORTED_VERSIONS, "requested": requested}}}

How to check

Send tools/list with protocol version 1900-01-01. The answer is error -32022, and its data.supported equals the versions server/discover lists. Send a legacy initialize. The error message names each supported version.

Sources

For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/agents-as-users/mcp-servers/protocol-version-errors">Agent Wranglers agents as users playbook</a>. In code you write, add a comment next to it with the same link.