Server API

The Server struct is the main component for building MCP servers.

Constructor

Server.init

pub fn init(config: ServerConfig) Server

Create a new MCP server.

Parameters:

Field	Type	Description
name	[]const u8	Server name (required)
version	[]const u8	Server version (required)
allocator	Allocator	Memory allocator
title	?[]const u8	Human-readable title
description	?[]const u8	Server description

Example:

var server = mcp.Server.init(.{
    .name = "my-server",
    .version = "1.0.0",
    .allocator = allocator,
});
defer server.deinit();

---

Lifecycle

Server.deinit

pub fn deinit(self: *Server) void

Clean up server resources.

Server.run

pub fn run(self: *Server, transport: TransportType) !void

Start the server with the specified transport.

Transport Types:

• .stdio - Standard I/O transport
• .{ .http = .{ .port = u16 } } - HTTP transport

Example:

try server.run(.stdio);
// or
try server.run(.{ .http = .{ .port = 8080 } });

---

Capabilities

Server.enableTools

pub fn enableTools(self: *Server) void

Enable the tools capability.

Server.enableResources

pub fn enableResources(self: *Server, subscribe: bool) void

Enable the resources capability.

Parameters:

• subscribe - Enable subscription support for resource changes

Server.enablePrompts

pub fn enablePrompts(self: *Server, listChanged: bool) void

Enable the prompts capability.

Server.enableLogging

pub fn enableLogging(self: *Server) void

Enable the logging capability.

---

Tools

Server.addTool

pub fn addTool(self: *Server, tool: Tool) !void

Register a tool with the server.

Tool struct:

pub const Tool = struct {
    name: []const u8,
    description: ?[]const u8 = null,
    handler: *const fn(Allocator, ?json.Value) ToolError!ToolResult,
    input_schema: ?json.Value = null,
};

Example:

try server.addTool(.{
    .name = "greet",
    .description = "Greet someone",
    .handler = greetHandler,
});

---

Resources

Server.addResource

pub fn addResource(self: *Server, resource: Resource) !void

Register a resource with the server.

Resource struct:

pub const Resource = struct {
    uri: []const u8,
    name: []const u8,
    mimeType: ?[]const u8 = null,
    description: ?[]const u8 = null,
    handler: *const fn(Allocator, []const u8) ResourceError![]ResourceContent,
};

Server.addResourceTemplate

pub fn addResourceTemplate(self: *Server, template: ResourceTemplate) !void

Register a resource template for dynamic URIs.

---

Prompts

Server.addPrompt

pub fn addPrompt(self: *Server, prompt: Prompt) !void

Register a prompt with the server.

Prompt struct:

pub const Prompt = struct {
    name: []const u8,
    title: ?[]const u8 = null,
    description: ?[]const u8 = null,
    arguments: ?[]const PromptArgument = null,
    handler: *const fn(Allocator, ?json.Value) PromptError![]PromptMessage,
};

---

Message Handling

Server.handleMessage

pub fn handleMessage(self: *Server, data: []const u8) !void

Process an incoming JSON-RPC message.

Server.sendResponse

pub fn sendResponse(self: *Server, message: Message) !void

Send a JSON-RPC response.

---

Complete Example

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

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    var server = mcp.Server.init(.{
        .name = "api-example-server",
        .version = "1.0.0",
        .description = "Demonstrates the full Server API",
        .allocator = allocator,
    });
    defer server.deinit();

    // Enable all capabilities
    server.enableTools();
    server.enableResources(true);
    server.enablePrompts(true);
    server.enableLogging();

    // Register components
    try server.addTool(.{
        .name = "echo",
        .description = "Echo back input",
        .handler = echoHandler,
    });

    try server.addResource(.{
        .uri = "file:///config.json",
        .name = "Configuration",
        .mimeType = "application/json",
        .handler = configHandler,
    });

    try server.addPrompt(.{
        .name = "summarize",
        .description = "Summarize text",
        .handler = summarizeHandler,
    });

    // Run
    try server.run(.stdio);
}