Protocol API
The protocol module provides JSON-RPC 2.0 and MCP protocol implementations.
Protocol Constants
protocol.PROTOCOL_VERSION
pub const PROTOCOL_VERSION = "2026-07-28";
pub const VERSION = PROTOCOL_VERSION; // AliasThe current MCP protocol version.
protocol.SUPPORTED_VERSIONS
pub const SUPPORTED_VERSIONS = [_][]const u8{
"2026-07-28", // Supported (default, latest active specification)
};List of MCP protocol versions actively supported and advertised by this library in server/discover. Only 2026-07-28 is served; earlier revisions are unsupported and deprecated.
protocol.DEPRECATED_VERSIONS
pub const DEPRECATED_VERSIONS = [_][]const u8{
"2025-11-25", // Unsupported / Deprecated (session/handshake removed)
"2025-06-18", // Unsupported / Deprecated (session/handshake removed)
"2025-03-26", // Unsupported / Deprecated (session/handshake removed)
"2024-11-05", // Unsupported / Deprecated (initial specification)
};| 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) |
JSON-RPC
Message Types
pub const Message = union(enum) {
request: Request,
notification: Notification,
response: Response,
error_response: ErrorResponse,
};Request
pub const Request = struct {
id: types.RequestId,
method: []const u8,
params: ?std.json.Value = null,
};Response
pub const Response = struct {
id: types.RequestId,
result: ?std.json.Value = null,
};Notification
pub const Notification = struct {
method: []const u8,
params: ?std.json.Value = null,
};ErrorResponse
pub const ErrorResponse = struct {
id: ?types.RequestId,
@"error": Error,
pub const Error = struct {
code: i32,
message: []const u8,
data: ?std.json.Value = null,
};
};Parsing
jsonrpc.parseMessage
pub fn parseMessage(allocator: std.mem.Allocator, data: []const u8) ParseError!ParsedMessageParse a JSON-RPC message from a string.
Example:
const parsed = try mcp.jsonrpc.parseMessage(allocator, json_string);
defer parsed.deinit();
const message = parsed.message;
switch (message) {
.request => |req| { /* handle request */ },
.notification => |notif| { /* handle notification */ },
.response => |resp| { /* handle response */ },
.error_response => |err| { /* handle error */ },
}Serialization
jsonrpc.serializeMessage
pub fn serializeMessage(allocator: std.mem.Allocator, message: Message) ![]u8Serialize a message to JSON.
Example:
const json = try mcp.jsonrpc.serializeMessage(allocator, message);
defer allocator.free(json);Factory Functions
jsonrpc.createRequest
pub fn createRequest(
id: types.RequestId,
method: []const u8,
params: ?std.json.Value,
) Requestjsonrpc.createResponse
pub fn createResponse(
id: types.RequestId,
result: ?std.json.Value,
) Responsejsonrpc.createNotification
pub fn createNotification(
method: []const u8,
params: ?std.json.Value,
) Notificationjsonrpc.createErrorResponse
pub fn createErrorResponse(
id: ?types.RequestId,
code: i32,
message: []const u8,
data: ?std.json.Value,
) ErrorResponseError Helpers
jsonrpc.createParseError
pub fn createParseError(data: ?std.json.Value) ErrorResponseCreate a parse error response (-32700).
jsonrpc.createInvalidRequest
pub fn createInvalidRequest(id: ?types.RequestId, data: ?std.json.Value) ErrorResponseCreate an invalid request error (-32600).
jsonrpc.createMethodNotFound
pub fn createMethodNotFound(id: types.RequestId, method: []const u8) ErrorResponseCreate a method not found error (-32601).
jsonrpc.createInvalidParams
pub fn createInvalidParams(id: types.RequestId, message: []const u8) ErrorResponseCreate an invalid params error (-32602).
jsonrpc.createInternalError
pub fn createInternalError(id: types.RequestId, data: ?std.json.Value) ErrorResponseCreate an internal error (-32603).
Error Codes
pub const ErrorCode = struct {
pub const PARSE_ERROR = -32700;
pub const INVALID_REQUEST = -32600;
pub const METHOD_NOT_FOUND = -32601;
pub const INVALID_PARAMS = -32602;
pub const INTERNAL_ERROR = -32603;
pub const SERVER_NOT_INITIALIZED = -32002;
pub const REQUEST_CANCELLED = -32800;
pub const CONTENT_TOO_LARGE = -32801;
};Transport
Transport Interface
pub const Transport = struct {
ptr: *anyopaque,
vtable: *const VTable,
pub const VTable = struct {
send: *const fn(...) anyerror!void,
receive: *const fn(...) anyerror!?[]const u8,
close: *const fn(...) void,
destroy: *const fn(...) void,
};
};StdioTransport
pub const StdioTransport = struct {
// Plain struct value, no init function: `var t: StdioTransport = .{};`
pub fn deinit(self: *StdioTransport, allocator: std.mem.Allocator) void;
pub fn send(self: *StdioTransport, io: std.Io, allocator: std.mem.Allocator, message: []const u8) Transport.SendError!void;
pub fn receive(self: *StdioTransport, io: std.Io, allocator: std.mem.Allocator) Transport.ReceiveError!?[]const u8;
pub fn transport(self: *StdioTransport) Transport;
};HttpTransport
pub const HttpTransport = struct {
pub fn init(allocator: std.mem.Allocator, endpoint: []const u8) !HttpTransport;
pub fn deinit(self: *HttpTransport, allocator: std.mem.Allocator) void;
pub fn send(self: *HttpTransport, io: std.Io, allocator: std.mem.Allocator, message: []const u8) Transport.SendError!void;
pub fn receive(self: *HttpTransport, io: std.Io, allocator: std.mem.Allocator) Transport.ReceiveError!?[]const u8;
pub fn setAuthorizationToken(self: *HttpTransport, allocator: std.mem.Allocator, token: []const u8) !void;
pub fn setClientInfo(self: *HttpTransport, allocator: std.mem.Allocator, name: []const u8, version: []const u8) !void;
pub fn transport(self: *HttpTransport) Transport;
};HTTP mode details:
- Clients send JSON-RPC with
POST /mcpandContent-Type: application/json. - Requests include
Accept: application/json, text/event-streamandMCP-Protocol-Version: 2026-07-28. - SSE is selected with
Accept: text/event-stream; the server replies withContent-Type: text/event-stream(data: <json>\n\n). - The protocol is stateless per-request; every request carries protocol version and client info in
_meta.
Authorization (mcp.auth)
Protocol-level authorization primitives for OAuth 2.0 / 2.1 authentication and resource discovery.
parseWwwAuthenticate
pub fn parseWwwAuthenticate(header: []const u8) WwwAuthenticateChallengeParses an HTTP WWW-Authenticate response challenge header. Extracts scheme, realm, resource_metadata, scope, error, and error_description.
fetchProtectedResourceMetadata & discoverProtectedResourceMetadata
pub fn fetchProtectedResourceMetadata(
allocator: std.mem.Allocator,
io: std.Io,
url: []const u8,
) !ProtectedResourceMetadata
pub fn discoverProtectedResourceMetadata(
allocator: std.mem.Allocator,
io: std.Io,
mcp_endpoint_url: []const u8,
www_authenticate_header: ?[]const u8,
) !ProtectedResourceMetadataFetches and discovers RFC 9728 OAuth 2.0 Protected Resource Metadata from challenge headers or automatic well-known URI probing.
discoverAuthorizationServerMetadata
pub fn discoverAuthorizationServerMetadata(
allocator: std.mem.Allocator,
io: std.Io,
issuer_url: []const u8,
) !AuthorizationServerMetadataProbes OAuth 2.0 and OpenID Connect discovery endpoints in priority order and validates the issuer against mix-up attacks (RFC 8414 Section 3.3).
requestClientCredentialsToken & requestClientCredentialsTokenWithResource
pub fn requestClientCredentialsToken(
allocator: std.mem.Allocator,
io: std.Io,
token_endpoint: []const u8,
client_id: []const u8,
client_secret: []const u8,
scope: ?[]const u8,
) !ClientCredentialsTokenResponse
pub fn requestClientCredentialsTokenWithResource(
allocator: std.mem.Allocator,
io: std.Io,
token_endpoint: []const u8,
client_id: []const u8,
client_secret: []const u8,
scope: ?[]const u8,
resource: ?[]const u8,
) !ClientCredentialsTokenResponseExecutes an RFC 6749 Section 4.4 Client Credentials Grant request with optional RFC 8707 Resource Indicators.
ClientIdMetadataDocument (CIMD)
pub const ClientIdMetadataDocument = struct {
client_id: []const u8,
client_name: []const u8,
client_uri: ?[]const u8 = null,
logo_uri: ?[]const u8 = null,
redirect_uris: []const []const u8 = &.{},
grant_types: ?[]const []const u8 = null,
response_types: ?[]const []const u8 = null,
token_endpoint_auth_method: []const u8 = "none",
pub fn validate(self: ClientIdMetadataDocument) bool;
pub fn deinit(self: *ClientIdMetadataDocument, allocator: std.mem.Allocator) void;
};
pub fn parseClientIdMetadataDocument(allocator: std.mem.Allocator, json_bytes: []const u8) !ClientIdMetadataDocument;generatePkce & verifyPkce (RFC 7636 / OAuth 2.1)
pub const PkcePair = struct {
verifier: [43]u8,
challenge: [43]u8,
method: []const u8 = "S256",
};
pub fn generatePkce(random: std.Random) PkcePair;
pub fn verifyPkce(verifier: []const u8, expected_challenge: []const u8) bool;validateTokenAudience (RFC 8707 / RFC 9728)
pub fn validateTokenAudience(token_audience: []const u8, expected_resource_uri: []const u8) bool;Validates inbound token audience claims on the server to prevent token reuse across services.
Cooperative Cancellation (mcp.CancellationToken)
Thread-safe atomic cancellation token for cooperative cancellation across tasks, tool handlers, and async workers:
pub const CancellationToken = struct {
pub fn init() CancellationToken;
pub fn cancel(self: *CancellationToken) void;
pub fn isCancelled(self: *const CancellationToken) bool;
pub fn reset(self: *CancellationToken) void;
pub fn check(self: *const CancellationToken) error{Cancelled}!void;
};Complete Example
const std = @import("std");
const mcp = @import("mcp");
pub fn main(init: std.process.Init) void {
run(init.io, init.gpa) catch |err| mcp.reportError(err);
}
fn run(_: std.Io, allocator: std.mem.Allocator) !void {
// Create a request
const request = mcp.jsonrpc.createRequest(
.{ .integer = 1 },
"tools/list",
null,
);
// Serialize to JSON
const json = try mcp.jsonrpc.serializeMessage(
allocator,
.{ .request = request },
);
defer allocator.free(json);
std.debug.print("Request: {s}\n", .{json});
// Parse a response
const response_json = "{\"jsonrpc\":\"2.0\",\"id\":1,\"result\":{}}";
const parsed = try mcp.jsonrpc.parseMessage(allocator, response_json);
defer parsed.deinit();
switch (parsed.message) {
.response => |resp| {
std.debug.print("Got response for ID: {any}\n", .{resp.id});
},
else => {},
}
}