Examples
Explore these complete, working examples to learn how to use mcp.zig effectively.
Available Examples
Servers
Simple Server
A minimal MCP server with greeting and echo tools, a resource, and a prompt.
Weather Server
A multi-tool server with InputSchema constraints, resource templates, and task support.
Calculator Server
Arithmetic tools with structured output schemas, annotations, and task-enabled division.
Advanced Server
Full feature showcase: JSON Schema 2020-12, icons, output schemas, task support, prompts.
Filesystem Server
Read files and list directories. Demonstrates real file I/O inside tool handlers.
Notes Server
Stateful server storing in-memory notes. Shows user_data context, list-change notifications.
HTTP Server
HTTP transport with SSE support. Includes ping and hash_text tools and a status resource.
Middleware Server
Logging and authentication middleware that intercepts tool calls.
Health Check Example
Built-in health/check endpoint for server status, uptime, and connections.
Shutdown Example
Graceful shutdown of an MCP server via a shutdown tool.
Validator Example
Request validation for tool arguments using RequestValidator.
Rate Limiter Example
Rate limiting for tool calls using RateLimiter.
MCP Apps Server
Interactive UI application server using the MCP Apps extension (io.modelcontextprotocol/ui), mcp.MIME_TYPE_MCP_APP, and _meta.ui.
Clients
Simple Client
A basic MCP client demonstrating capability declaration, roots, and server discovery.
Batch Client
Sends multiple JSON-RPC requests as a batch using BatchRequest.
Full Client
Exercises every client-side operation against a real in-process server, including tools/call, resources/read and prompts/get, and asserts on each response.
Running Examples
All examples are included in the examples/ directory of the repository.
Build All Examples
zig build run-all-examplesRun a Server Example
# Simple server
./zig-out/bin/example-server
# Weather server
./zig-out/bin/weather-server
# Calculator
./zig-out/bin/calculator-server
# Advanced server
./zig-out/bin/advanced-server
# Filesystem server
./zig-out/bin/filesystem-server
# Notes server
./zig-out/bin/notes-server
# HTTP server
./zig-out/bin/http-server
# Middleware server
./zig-out/bin/middleware-server
# Health check
./zig-out/bin/health-check-example
# Shutdown
./zig-out/bin/shutdown-example
# Validator
./zig-out/bin/validator-example
# Rate limiter
./zig-out/bin/rate-limiter-example
# MCP Apps server
./zig-out/bin/mcp-app-serverPowerShell (Windows):
.\zig-out\bin\example-server.exe
.\zig-out\bin\weather-server.exe
.\zig-out\bin\calculator-server.exe
.\zig-out\bin\advanced-server.exe
.\zig-out\bin\filesystem-server.exe
.\zig-out\bin\notes-server.exe
.\zig-out\bin\http-server.exe
.\zig-out\bin\middleware-server.exe
.\zig-out\bin\health-check-example.exe
.\zig-out\bin\shutdown-example.exe
.\zig-out\bin\validator-example.exe
.\zig-out\bin\rate-limiter-example.exe
.\zig-out\bin\mcp-app-server.exeRun a Client Example
# Simple client (connects to a server)
./zig-out/bin/example-client ./zig-out/bin/example-server
# Batch client
./zig-out/bin/batch-client ./zig-out/bin/example-serverPowerShell (Windows):
.\zig-out\bin\example-client.exe .\zig-out\bin\example-server.exe
.\zig-out\bin\batch-client.exe .\zig-out\bin\example-server.exeTesting with an AI Client
You can test your MCP server with Claude Desktop or other MCP-compatible AI clients.
Claude Desktop Configuration
Add to your Claude Desktop config (usually at ~/.config/claude/config.json):
{
"mcpServers": {
"my-server": {
"command": "/path/to/zig-out/bin/example-server"
}
}
}Manual Testing with curl (HTTP Server)
# Start the HTTP server
./zig-out/bin/http-server
# Discover
curl -X POST http://127.0.0.1:8080/mcp \
-H "Content-Type: application/json" \
-H "MCP-Protocol-Version: 2026-07-28" \
-H "Mcp-Method: server/discover" \
-d '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"test","version":"1.0.0"}}}}'
# Call ping
curl -X POST http://127.0.0.1:8080/mcp \
-H "Content-Type: application/json" \
-H "MCP-Protocol-Version: 2026-07-28" \
-H "Mcp-Method: tools/call" \
-H "Mcp-Name: ping" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ping","arguments":{"message":"hello"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"test","version":"1.0.0"}}}}'Project Structure
examples/
├── simple_server.zig # Minimal server (greet, echo)
├── simple_client.zig # Client with roots and capabilities
├── weather_server.zig # Weather tools + resource template
├── calculator_server.zig # Arithmetic with output schemas
├── advanced_server.zig # Full feature showcase
├── filesystem_server.zig # File I/O via tools and resources
├── notes_server.zig # Stateful notes store (user_data)
├── http_server.zig # HTTP transport + SSE example
├── middleware_server.zig # Logging and auth middleware
├── health_check_example.zig # Built-in health/check endpoint
├── shutdown_example.zig # Graceful shutdown
├── validator_example.zig # Request validation
├── rate_limiter_example.zig # Rate limiting
└── batch_client.zig # Batch JSON-RPC requestsCreating Your Own Examples
- Create a new file in the
examples/directory - Add it to
build.zig - Import
mcpand start building!
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(io: std.Io, allocator: std.mem.Allocator) !void {
var server = mcp.Server.init(allocator, .{
.name = "my-server",
.version = "1.0.0",
});
defer server.deinit();
// Add tools, resources, prompts...
try server.addTool(.{
.name = "my_tool",
.description = "Does something useful",
.handler = myHandler,
});
try server.run(io, allocator, .stdio);
}
fn myHandler(_: ?*anyopaque, _: std.Io, allocator: std.mem.Allocator, _: ?std.json.Value) mcp.tools.ToolError!mcp.tools.ToolResult {
return mcp.tools.textResult(allocator, "Hello from my tool!") catch return mcp.tools.ToolError.OutOfMemory;
}