Examples

Examples

The examples/ directory has small programs for each transport. zig build examples builds all of them into zig-out/bin/. zig build run-<name> builds and runs one of them, such as zig build run-stdio_server. Each program is one file. A doc comment at its top tells you how to run it.

Applies to: zig-sdk 0.1.0. The programs unix_server, websocket_server and authorization_server, and the modes unix, ws and --oauth of client_cli: zig-sdk 0.2.0.

The programs

Program	What it shows
stdio_server	A server over stdio with one tool, one resource and one prompt.
https_server	A server over HTTPS with the in-tree TLS 1.3 server. Arguments: the certificate and the key in PEM, and the port.
grpc_server	A server over the JSON-RPC tunnel of the gRPC binding, cleartext or TLS with ALPN h2. Arguments: the port, and for TLS the certificate and the key in PEM. The default port is 50051.
grpc_client	A client over the JSON-RPC tunnel of the gRPC binding that discovers the server, lists the tools and calls add. Arguments: the host, the port and a CA file in PEM. With the CA file, it connects with TLS.
unix_server	A server on a Unix domain socket with one tool. Argument: the path of the socket file in a private directory. By default it creates the private directory mcp-run and uses mcp-run/mcp.sock.
websocket_server	A server on WebSocket connections with one tool. Arguments: the port, and for wss the certificate and the key in PEM. The default is ws://127.0.0.1:3001/mcp.
authorization_server	An authorization server and an MCP server in one process, with a consent page. The MCP server accepts the bearer and DPoP-bound tokens of the authorization server. Arguments: the port of the authorization server and the port of the MCP server. The defaults are 9000 and 3000.
client_cli	A client for the command line over stdio, Streamable HTTP, a Unix domain socket or WebSocket. It lists the tools or calls one. With http <url> --oauth, it signs in with OAuth and keeps the tokens in the keychain of the host. Without a keychain, it keeps them in encrypted files when MCP_TOKEN_KEY has a key of 64 hexadecimal digits.
consumer/	A separate project that depends on the SDK with b.dependency("mcp", ...). zig build examples does not build it. Run zig build in its directory.

Steps: try the CLI against the stdio server

1. Build the examples:

zig build examples

2. List the tools of the stdio server:

./zig-out/bin/client_cli stdio ./zig-out/bin/stdio_server -- list

3. Call a tool with JSON arguments:

./zig-out/bin/client_cli stdio ./zig-out/bin/stdio_server -- call add '{"a":2,"b":3}'

Steps: try the Unix socket pair

1. Start the server. It creates the private directory mcp-run and the socket file mcp-run/mcp.sock:

./zig-out/bin/unix_server

2. List the tools in another shell:

./zig-out/bin/client_cli unix mcp-run/mcp.sock -- list

3. Call a tool with JSON arguments:

./zig-out/bin/client_cli unix mcp-run/mcp.sock -- call add '{"a":2,"b":3}'

See Transport Unix Socket.

Steps: try the WebSocket pair

1. Start the server:

./zig-out/bin/websocket_server

2. List the tools in another shell:

./zig-out/bin/client_cli ws ws://127.0.0.1:3001/mcp -- list

3. Call a tool with JSON arguments:

./zig-out/bin/client_cli ws ws://127.0.0.1:3001/mcp -- call add '{"a":2,"b":3}'

See Transport WebSocket.

Steps: try the gRPC pair

1. Start the server on port 50051:

./zig-out/bin/grpc_server 50051

2. Run the client in another shell:

./zig-out/bin/grpc_client 127.0.0.1 50051

The client logs the server name, the tools and the result of add(40, 2), with one progress notification.

Steps: try HTTPS

1. Start the server with the test certificate:

./zig-out/bin/https_server test/fixtures/tls/pem/p256.crt test/fixtures/tls/pem/p256.key 8443

2. Call it with curl:

curl -k --tlsv1.3 -X POST https://127.0.0.1:8443/mcp -H "content-type: application/json" -H "accept: application/json, text/event-stream" -H "mcp-protocol-version: 2026-07-28" -H "mcp-method: server/discover" --data-binary '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}'

The client_cli program can call the same server with http https://127.0.0.1:8443/mcp. It uses the system trust store, so it refuses the test certificate.

The conformance fixtures

conformance/everything_server.zig and conformance/everything_client.zig are larger programs that cover every feature the official suite checks. See Conformance.