Supported Protocol Version
Official Documentation
This library implements Model Context Protocol (MCP) version 2026-07-28. For the official MCP changelog and full specification, please visit modelcontextprotocol.io.
protocol.PROTOCOL_VERSION is 2026-07-28. It is the only revision this library speaks: there is no negotiation down to an earlier revision and no legacy fallback.
Key Changes in Protocol 2026-07-28
The following breaking changes were introduced in the MCP specification revision 2026-07-28:
Breaking Changes
- Stateless Protocol: No more
initialize/notifications/initializedhandshake. Every request carriesio.modelcontextprotocol/protocolVersion,io.modelcontextprotocol/clientCapabilities, andio.modelcontextprotocol/clientInfoin_meta; a request missing the version or the capabilities is answered with-32602. server/discover: Now a mandatory RPC that servers MUST implement (replaces initialization). ReturnssupportedVersionsandcapabilities, with the server identity under the namespaced_metakeyio.modelcontextprotocol/serverInfo.- MRTR (Multi Round-Trip Requests): Servers use
InputRequiredResultwithresultType: "input_required"and aninputRequestsfield instead of server-initiated JSON-RPC requests (sampling, elicitation, roots). The client answers and retries the original request with a new id, carrying the same params plusinputResponsesand the opaquerequestStateverbatim. subscriptions/listen: Replacesresources/subscribe/resources/unsubscribeand the HTTP GET endpoint. The server acknowledges with the subscription id and the subset of the filter it agreed to honour, then keeps the stream open. Change notifications are delivered only to subscribers whose filter admits them, each tagged with the subscription id in_meta. The client opens one withsubscriptionsListen(.{ .toolsListChanged = true })and ends it withcancel; the server tears it down withServer.endSubscription.- No protocol-level sessions on Streamable HTTP.
Mcp-Session-Idremoved. Servers are stateless per-request. - All results carry
resultType:"complete","input_required", or"task"(the tasks extension). - Removed in this revision:
ping,logging/setLevel(log level is now per-request viaio.modelcontextprotocol/logLevelin_meta),notifications/roots/list_changed,resources/subscribe/resources/unsubscribe,Mcp-Session-Id, and SSE resumability.tasks/resultandtasks/listare replaced bytasks/get,tasks/updateandtasks/cancel. - New HTTP headers:
MCP-Protocol-Version,Mcp-Method,Mcp-Name,Mcp-Param-*(from toolx-mcp-headerannotations). - Caching:
ttlMsandcacheScoperequired onserver/discover,tools/list,prompts/list,resources/list,resources/templates/list,resources/readresults.
Additions in this revision
These are new capabilities rather than replacements, and mcp.zig implements each of them:
- Tasks extension (
io.modelcontextprotocol/tasks), declared as an extension label on both sides in place of the old per-method task capabilities. _metakey naming rules with a reverse-DNS prefix convention.iconson implementations, tools, prompts, and resources.outputSchemafor structured tool results, carried alongsidestructuredContent.completion/completefor argument autocompletion.- Tool name rules: 1-128 characters, case-sensitive, alphanumeric plus underscore, hyphen, or dot (
mcp.tools.isValidToolName).
Implementation notes
Server identity:
serverInfois emitted under the namespaced_metakeyio.modelcontextprotocol/serverInfo, not as a top-level result field, matching the 2026-07-28DiscoverResultshape.resultType: every completed result carriesresultType: "complete". The client accepts an absentresultTypefrom an earlier-protocol server and rejects any value it does not recognise (complete,input_required, or the tasks extension'stask) witherror.UnknownResultType.MRTR retries are not cacheable: a request carrying
inputResponsesorrequestStateis a retry rather than a fresh call, so its result is emitted withoutttlMs/cacheScope. Those fields depend on inputs that are not part of the cache key.Invalid cursors are rejected: an undecodable
cursorreturns-32602rather than silently restarting from the first page. A cursor counts as absent only when thecursormember is missing or is not a string.Caching hints: emitted automatically on the six cacheable operations. Defaults are
ttlMs = 300000/cacheScope = "public"for lists andserver/discover, andttlMs = 60000/cacheScope = "private"forresources/read. Override them through the server'scacheconfiguration:zigvar server = mcp.Server.init(allocator, .{ .name = "my-server", .version = "1.0.0", .cache = .{ .ttl_ms = 60_000, .scope = .private, .read_ttl_ms = 0, .read_scope = .private, }, });Negative
ttl_msvalues are clamped to0(immediately stale).Deterministic ordering:
tools/list,prompts/list,resources/list, andresources/templates/listreturn entries sorted by name so clients can cache and diff lists reliably.Error codes restructured:
-32020(HeaderMismatch),-32021(MissingRequiredClientCapability),-32022(UnsupportedProtocolVersion).Streamable HTTP: GET endpoint removed, SSE resumability via
Last-Event-IDremoved. Per-request SSE stream lifetime is also not implemented in this library, because the transport interface exchanges whole messages; the HTTP client acceptstext/event-streamresponses, and the server answers one POST with one response.Tasks: a
tools/callis augmented through_meta["io.modelcontextprotocol/task"]({"ttl": <ms>}), never through ataskrequest parameter. The result carriesresultType: "task", atasksnapshot, and_meta["io.modelcontextprotocol/relatedTask"] = {"taskId": ...}; progress is pushed asnotifications/tasksto the subscriptions that listed the task id intypes.SubscriptionFilter.taskIds.tasks/get,tasks/updateandtasks/cancelare refused with-32021unless the client declared the extension.Cancellation: cooperative and poll-based.
notifications/cancelledrecords the request id; a handler observes it throughServer.cancellationToken(id)(cancelled(),keepGoing()) and the server answers with-32800. A synchronous handler that never polls its token cannot be interrupted.Authorization: the OAuth 2.1 framework and Protected Resource Metadata (RFC 9728) are part of the specification, but not implemented here. Only
Client.setAuthorizationToken(a static bearer token) exists; see Authorization.
Version Support
| Version | Status |
|---|---|
| 2026-07-28 | Supported (latest, default; the active revision this library speaks and serves) |
| 2025-11-25 | Unsupported / Deprecated (older session-based revision; methods removed in 2026-07-28) |
| 2025-06-18 | Unsupported / Deprecated (older session-based revision; methods removed in 2026-07-28) |
| 2025-03-26 | Unsupported / Deprecated (older session-based revision; methods removed in 2026-07-28) |
| 2024-11-05 | Unsupported / Deprecated (initial specification; methods removed in 2026-07-28) |
Earlier revisions (2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05) are deprecated and unsupported. They established a session with an initialize handshake and are not supported: the methods they rely on were removed in 2026-07-28. In accordance with the 2026-07-28 specification, protocol.SUPPORTED_VERSIONS and server/discover advertise only the revisions the server can actually serve: ["2026-07-28"]. Requests specifying older revisions in the MCP-Protocol-Version HTTP header or body _meta are rejected with -32022 (UnsupportedProtocolVersion).
