Transports - ChristianPresley/zig-sdk GitHub Wiki

Transports

A transport carries JSON-RPC messages between a client and a server. Revision 2026-07-28 defines stdio and Streamable HTTP1. The SDK has both, and HTTPS through its own TLS 1.3 server and client. It also has an in-memory link, a gRPC binding with two services, a Unix socket transport and a WebSocket transport. This page compares the transports and links to the page of each one.

Applies to: MCP 2026-07-28, Zig 0.16.0, zig-sdk 0.1.0. The typed gRPC binding, the Unix socket transport and the WebSocket transport: zig-sdk 0.2.0. The documented limits of the in-memory link: zig-sdk 0.4.0.

Overview

Transport Server Client Page
stdio mcp.transport.stdio.serve mcp.transport.stdio.Client.spawn Transport stdio
Streamable HTTP mcp.transport.http.Server mcp.transport.HttpClient Transport Streamable HTTP
HTTPS The HTTP server with the tls option The HTTP client with an https URL TLS and Certificates
gRPC tunnel mcp_grpc.Server mcp_grpc.Channel Transport gRPC
gRPC typed mcp_grpc.Server with bindings.typed mcp_grpc.TypedChannel Transport gRPC
Unix socket mcp.transport.unix.Server mcp.transport.unix.Client.connect Transport Unix Socket
WebSocket mcp.transport.websocket.Server mcp.transport.websocket.Client Transport WebSocket
In-memory mcp.transport.memory.Harness mcp.transport.memory.ClientLink This page

All transports give the same messages to the server engine. A handler does not know which transport carries its request.

stdio

The server reads one JSON-RPC message per line from standard input and writes one message per line to standard output2. The client starts the server as a child process. It ends the process tree when it closes. It can start the server again after a crash. See Transport stdio.

Streamable HTTP

The server accepts POST on one path, /mcp by default3. It answers with application/json for a plain result, or with text/event-stream when the request sends notifications or is long-lived. The HTTP headers mirror the method, the name and the annotated tool parameters of each request4. The server binds to 127.0.0.1 by default and accepts loopback origins only. See Transport Streamable HTTP and Deploy Reverse Proxy.

HTTPS

Set Options.tls to a mcp.tls.Server and the same HTTP server speaks TLS 1.3. The HTTP client uses the SDK TLS client for an https URL. See TLS and Certificates.

In-memory link

mcp.transport.memory.ClientLink connects a client to a server in the same process. It has no task of its own. You can use it in production with these limits:

  • The handler of a request runs on the task of the caller. The events of a listen stream get to the callbacks on the task that publishes them.
  • Only the cancel token of the caller ends an exchange. The link does not obey RequestOptions.timeout, limits.request_timeout and limits.listen_ack_timeout.
  • The link ignores RequestOptions.inline_notifications.
  • A callback of a listen stream runs while the server holds the lock of the stream. Thus it must not publish an event of the same server. See Server Guide.

mcp.transport.memory.Harness is for tests. It sends raw frames to a server and collects the frames of the answer.

gRPC

The gRPC binding is a custom transport under the rules of the specification for custom transports1. It keeps the JSON-RPC format and the request patterns:

  • One server-streaming Call RPC per MCP request. The request message carries the JSON-RPC request. The stream carries notifications and then the response.
  • subscriptions/listen is one long-lived call.
  • Cancellation is RST_STREAM(CANCEL).
  • Metadata mirrors the HTTP headers in lowercase: mcp-protocol-version, mcp-method, mcp-name, mcp-param-* and authorization.

The server can also serve the typed service model_context_protocol.Mcp of the Google Cloud proto files on the same port. Each of its eight unary RPCs carries one MCP request as a typed message. mcp_grpc.TypedChannel is its client.

The binding is in the module mcp_grpc, with its own protobuf, HPACK, HTTP/2 and gRPC layers. See Transport gRPC for the normative description, the errors and the limits.

Unix socket

The Unix socket transport is a custom transport under the rules of the specification for custom transports1. It uses the stdio framing on a stream socket at a file system path. The server accepts many connections, and each connection behaves as one stdio peer.

On POSIX systems the server sets the mode 0600 on the socket file. On Windows it gives the socket file an access control list for the user only. The directory of the socket must be private. See Transport Unix Socket.

WebSocket

The WebSocket transport is a custom transport under the rules of the specification for custom transports1. It carries one JSON-RPC message in each text message of an RFC 6455 connection5 with the subprotocol mcp. One connection carries many requests. The client cancels a request with notifications/cancelled, as on stdio. The server checks the access token at the upgrade and closes the connection when the token expires. See Transport WebSocket.

References

  1. MCP-TRANSPORTS-2026-07-28: Transports, and the rules for custom transports.
  2. MCP-STDIO-2026-07-28: stdio transport.
  3. MCP-HTTP-2026-07-28: Streamable HTTP transport.
  4. MCP-SEP-2243: HTTP headers derived from the message.
  5. RFC6455: The WebSocket Protocol.
⚠️ **GitHub.com Fallback** ⚠️