Skip to content

Server API ​

mcp.Server is the core runtime for exposing tools, resources, prompts, and utility notifications.

Constructor ​

zig
pub fn init(allocator: std.mem.Allocator, config: ServerConfig) Server

Important ServerConfig fields:

FieldTypeDescription
name[]const u8Required server name
version[]const u8Required server version
title?[]const u8Optional human-readable title
description?[]const u8Optional description
icons?[]const mcp.types.IconOptional icon list
websiteUrl?[]const u8Optional website URL
instructions?[]const u8Optional usage instructions
cacheCacheConfigCaching hints for cacheable results

CacheConfig ​

Servers MUST emit ttlMs (>= 0) and cacheScope on resultType: "complete" results for server/discover, tools/list, prompts/list, resources/list, resources/templates/list, and resources/read.

FieldTypeDefaultDescription
ttl_msi64300000Freshness hint in ms for lists and server/discover; negatives clamp to 0
read_ttl_msi6460000Freshness hint for resources/read
scopetypes.CacheScope.publicCache scope for lists and server/discover
read_scopetypes.CacheScope.privateCache scope for resources/read

types.CacheScope is either .public (no user-specific data) or .private (must not be shared across authorization contexts).

Lifecycle ​

zig
pub fn deinit(self: *Server) void
pub fn run(self: *Server, io: std.Io, allocator: std.mem.Allocator, options: RunOptions) !void
pub fn runWithTransport(self: *Server, io: std.Io, allocator: std.mem.Allocator, t: mcp.transport.Transport) !void

Run options:

OptionDescription
.stdioLine-delimited JSON-RPC over stdin/stdout
.{ .http = .{ .host = "127.0.0.1", .port = 8080 } }HTTP listener with JSON-RPC POST on /mcp

Note: HTTP mode accepts host names such as 127.0.0.1 and binds accordingly. It is implemented with httpx.zig 0.2.2 (Zig 0.17.0).

Registration ​

zig
pub fn addTool(self: *Server, tool: mcp.tools.Tool) !void
pub fn addResource(self: *Server, resource: mcp.resources.Resource) !void
pub fn addResourceTemplate(self: *Server, template: mcp.resources.ResourceTemplate) !void
pub fn addPrompt(self: *Server, prompt: mcp.prompts.Prompt) !void

Capability & Extension Toggles ​

zig
pub fn enableLogging(self: *Server) void
pub fn enableCompletions(self: *Server) void
pub fn enableTasks(self: *Server) !void
pub fn enableUi(self: *Server) !void
pub fn enableUiWithSettings(self: *Server, settings: std.json.Value) !void
pub fn isUiEnabled(self: *Server) bool
pub fn isTasksEnabled(self: *Server) bool

Tools/resources/prompts capabilities are advertised automatically once components are registered.

Utility Notifications ​

zig
pub fn sendNotification(self: *Server, io: std.Io, allocator: std.mem.Allocator, method: []const u8, params: ?std.json.Value) !void
pub fn sendLogMessage(self: *Server, io: std.Io, allocator: std.mem.Allocator, level: mcp.protocol.LogLevel, message: []const u8) !void
pub fn sendProgress(self: *Server, io: std.Io, allocator: std.mem.Allocator, token: std.json.Value, prog: f64, total: ?f64, message: ?[]const u8) !void

pub fn notifyToolsChanged(self: *Server, io: std.Io, allocator: std.mem.Allocator) !void
pub fn notifyResourcesChanged(self: *Server, io: std.Io, allocator: std.mem.Allocator) !void
pub fn notifyResourceUpdated(self: *Server, io: std.Io, allocator: std.mem.Allocator, uri: []const u8) !void
pub fn notifyPromptsChanged(self: *Server, io: std.Io, allocator: std.mem.Allocator) !void

Log level is per-request

Logging is opt-in per request. A client asks for logs by putting io.modelcontextprotocol/logLevel in that request's _meta, and the server emits nothing when the field is absent. sendLogMessage therefore only delivers while the request that asked for logs is still being handled, and a message below the requested level is dropped. An unrecognized level fails the request with -32602. The connection-wide logging/setLevel method was removed in 2026-07-28.

Minimal Example ​

zig
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 = "api-example-server",
        .version = "1.0.0",
    });
    defer server.deinit();

    try server.addTool(.{
        .name = "ping",
        .description = "Returns pong",
        .handler = struct {
            fn handler(_: ?*anyopaque, _: std.Io, alloc: std.mem.Allocator, _: ?std.json.Value) mcp.tools.ToolError!mcp.tools.ToolResult {
                return mcp.tools.textResult(alloc, "pong") catch return mcp.tools.ToolError.OutOfMemory;
            }
        }.handler,
    });

    server.enableLogging();
    try server.run(io, allocator, .stdio);
}