Concepts

Concepts

This page explains the protocol model of MCP revision 2026-07-28 and the words this wiki uses for it. The revision made the protocol stateless¹. Each request carries everything the server needs.

Applies to: MCP 2026-07-28, zig-sdk 0.1.0. The timeouts, the rate of progress notifications, the principal binding of requestState and the credential of the client cache: zig-sdk 0.2.0. The Unix socket transport and the WebSocket transport: the same release.

Messages

MCP uses JSON-RPC 2.0 messages². A request has an id that is a string or an integer. A notification has no id. The SDK echoes each id byte for byte, also for integers that are larger than 64 bits.

There is no initialize handshake and there are no sessions in this revision³. A client learns the server capabilities with the server/discover request.

Request metadata

Every request carries a _meta object with two mandatory fields⁴:

• io.modelcontextprotocol/protocolVersion: the revision the client speaks.
• io.modelcontextprotocol/clientCapabilities: the capabilities of the client.

A request without these fields gets the error -32602. A request with a revision the server does not speak gets the error -32022. The error data lists the supported revisions. A tool that needs a client capability the client did not declare gets the error -32021.

Results

Every result carries resultType. The value complete means that the request is complete. The value input_required means the server needs input from the client before it can complete the request. The SDK treats a result without resultType as complete, and it counts this as a violation in the diagnostics.

Multi round-trip requests

A server cannot send requests to a client in this revision. When a tool needs input, the server answers with resultType: "input_required" and a set of input requests⁵. The client answers each input request and sends the original request again with a new id, the answers and the opaque requestState.

The SDK seals requestState with AES-256-GCM, because the client can change it. A changed or expired state gets the error -32602. When the transport checked a bearer token, the SDK also binds the state to the principal: the issuer, the subject and the client id. The state of another principal gets the error -32602 too.

Subscriptions

A client opens one long-lived subscriptions/listen request and tells which events it wants⁶. The server first acknowledges the subscription, then sends events as notifications on the same stream. Every event carries the subscription id.

Cancellation and timeouts

A client cancels a request with notifications/cancelled on stdio, on a Unix socket and on WebSocket⁹. On HTTP, the client closes the connection, and on gRPC, it resets the stream. After a cancellation by the client, the server sends nothing more for the request. The reason text of a cancellation has no effect on the behavior. The SDK logs the id and the reason of each notifications/cancelled that it receives. The log has the debug level and the log scope mcp_cancel.

The SDK client gives each request a timeout. The default is limits.request_timeout (60 s), and the upper limit is limits.max_total_timeout (600 s). Progress notifications do not extend the timeout. A listen stream has no default timeout. At the end of the timeout, the client cancels the request. The memory link (memory.ClientLink) does not obey these time limits.

The server and the client limit the progress notifications of one request to limits.max_progress_rate_per_s (50) per second¹⁰. The server does not send the progress notifications over this rate, and the client does not give them to the application.

Caching

The results of discovery, list and read requests carry ttlMs and cacheScope⁷. The SDK stamps both. The default is no caching (ttlMs: 0, cacheScope: "private"). The client cache is off by default. When it is on, the client serves a private result only for the credential of the request that got it. See Client Guide.

Transports

A transport carries the messages. The SDK has stdio, Streamable HTTP and HTTPS. The SDK also has a gRPC binding, a Unix socket transport and a WebSocket transport as custom transports⁸. See Transports.

References

1. MCP-CHANGELOG-2026-07-28: Key changes of revision 2026-07-28.
2. JSONRPC2: JSON-RPC 2.0 Specification.
3. MCP-LIFECYCLE-2026-07-28: Lifecycle in revision 2026-07-28.
4. MCP-BASIC-2026-07-28: Base protocol.
5. MCP-MRTR-2026-07-28: Multi round-trip requests.
6. MCP-SUBSCRIPTIONS-2026-07-28: Subscriptions.
7. MCP-CACHING-2026-07-28: Caching.
8. MCP-TRANSPORTS-2026-07-28: Transports, and the rules for custom transports.
9. MCP-CANCELLATION-2026-07-28: Cancellation of requests.
10. MCP-PROGRESS-2026-07-28: Progress notifications and their rate.