Getting Started

Getting Started

This page tells you how to add zig-sdk to a Zig project and how to run the first MCP server. You need Zig 0.16.0¹. The SDK has no other dependency.

Applies to: MCP 2026-07-28, Zig 0.16.0, zig-sdk 0.1.0.

Steps: add the dependency

1. Install Zig 0.16.0 from the official download page².
2. In your project, run this command. Replace the tag with the release you want. The command adds the dependency mcp to build.zig.zon.

zig fetch --save-exact git+https://github.com/ChristianPresley/zig-sdk#v0.5.1

3. In build.zig, get the module and add it to your executable. The examples on this page use an executable with the name calc.

const mcp_dep = b.dependency("mcp", .{ .target = target, .optimize = optimize });
exe.root_module.addImport("mcp", mcp_dep.module("mcp"));

4. Run zig build to confirm that the module resolves.

Steps: write a stdio server

1. Create src/main.zig with this content:

const std = @import("std");
const mcp = @import("mcp");

const AddArgs = struct {
    a: i64,
    b: i64,
    pub const json_schema = .{ .description = "Add two integers." };
};

fn add(ctx: *mcp.RequestContext, args: AddArgs) anyerror!mcp.Outcome(mcp.CallToolResult) {
    return .{ .complete = try mcp.CallToolResult.text(ctx.arena, "{d}", .{args.a + args.b}) };
}

pub fn main(init: std.process.Init) !void {
    var server = try mcp.Server.init(init.gpa, init.io, .{
        .info = .{ .name = "calc", .version = "0.1.0" },
    });
    defer server.deinit();
    try server.addTool(.{ .name = "add", .description = "Add two integers" }, add);
    try mcp.transport.stdio.serve(init.io, init.gpa, &server);
}

2. Run zig build.
3. Send a request to the server on its standard input. The request must carry _meta with the protocol version and the client capabilities³:

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}' | ./zig-out/bin/calc

4. Read the response on standard output. It lists the add tool with the schema that the SDK derived from AddArgs.

Steps: connect with the client

1. Spawn the server process and connect a client:

const proc = try mcp.transport.stdio.Client.spawn(init.io, init.gpa, .{ .argv = &.{"./zig-out/bin/calc"} });
defer proc.deinit();
var client: mcp.Client = .init(init.gpa, init.io, .{ .info = .{ .name = "cli", .version = "0.1.0" } });
defer client.deinit();
client.connect(proc.transport());

2. Call the tool. The arena owns the result:

const result = try client.callTool(arena, "add", .{ .a = 2, .b = 3 }, .{ .timeout = .fromSeconds(10) });
std.debug.print("{s}\n", .{result.content[0].text.text});

What to read next

• Server Guide for resources, prompts, completion and multi round-trip requests.
• Client Guide for the HTTP transport and the hooks.
• Transports for HTTPS, gRPC, the Unix socket transport and the WebSocket transport.
• Examples for the example programs and the client_cli command line client.
• API Reference for the reference of each module.
• VS Code on the wiki of zig-bridge-sdk, when VS Code must use your server. VS Code speaks revision 2025-11-25 and needs the bridge.

References

1. ZIG-0.16-RELNOTES: Zig 0.16.0 release notes.
2. ZIG-DOWNLOAD-INDEX: Zig download index.
3. MCP-BASIC-2026-07-28: Base protocol, the _meta fields of every request.