McpServerHandler Module

Table of Contents

• Introduction to the McpServerHandler Module
  • Basic server setup
  • Notifications
  • Tasks API
  • Resource Features
  • Progress Notifications
  • Sampling and Elicitation
• McpServerHandler Release Notes
  • McpServerHandler v1.1
  • McpServerHandler v1.0

Introduction to the McpServerHandler Module

The McpServerHandler module provides server-side support for the Model Context Protocol (MCP) using the HttpServer module. It exposes tools, resources, prompts, and notifications via JSON-RPC over HTTP and Server-Sent Events (SSE).

This module implements the full MCP 2025-11-25 protocol specification.

The following classes are provided by this module:

• McpServerHandler
• McpServerConnection

Basic server setup

%requires McpServerHandler
%requires HttpServer
 
Logger logger("mcp-server", LoggerLevel::getLevelInfo());
McpServerHandler::McpServerHandler handler(logger);
 
# register a tool
handler.registerTool("echo", "Echo a message", NOTHING, sub (hash<auto> args) {
    return {
        "content": [ { "type": "text", "text": args.message } ],
    };
});
 
# register a resource
handler.registerResource("file:///hello.txt", "Hello", "Simple text resource", "text/plain",
    sub (hash<auto> cx, hash<auto> params) {
        return { "contents": [ { "uri": params.uri, "text": "Hello from MCP" } ] };
    });
 
# register a prompt
handler.registerPrompt("greeting", "Greeting prompt", (
    { "name": "name", "description": "Name to greet", "required": True }
), sub (hash<auto> cx, hash<auto> params) {
    return {
        "messages": [
            { "role": "user", "content": [ { "type": "text", "text": "Hello " + params.arguments.name } ] }
        ]
    };
});
 
# start HTTP server
HttpServer http({"logger": logger});
http.setHandler("mcp", "", MimeTypeJson, handler);
http.setDefaultHandler("mcp", handler);
http.addListener({"service": 8080});

Notifications

The handler supports MCP notifications over SSE. Clients can open a GET request with an Accept: text/event-stream header to receive notifications and streamed responses.

Tasks API

The handler supports the MCP Tasks API for background task execution:

• tasks/get: Get task status by ID
• tasks/result: Block until task completes and return result
• tasks/cancel: Cancel a running task
• tasks/list: List all tasks for the session

To execute a tool call as a background task, include _meta.task: true in the request.

Resource Features

The handler supports:

• Resource subscriptions via resources/subscribe and resources/unsubscribe
• Resource templates via resources/templates/list
• Resource update notifications via notifications/resources/updated

Progress Notifications

The server can send progress notifications using the sendProgress() method. Include _meta.progressToken in requests to enable progress tracking.

Sampling and Elicitation

The server can request LLM completions from the client using requestSampling() and user input using requestElicitationForm() (requires client capability support).

McpServerHandler Release Notes

McpServerHandler v1.1

• Added full MCP 2025-11-25 protocol support:
  • Tasks API (tasks/get, tasks/result, tasks/cancel, tasks/list)
  • Task-augmented tool calls (_meta.task parameter)
  • Resource subscriptions (resources/subscribe, resources/unsubscribe)
  • Resource templates (resources/templates/list)
  • Progress notifications (notifications/progress)
  • Full request cancellation support
  • Server-to-client sampling requests
  • Server-to-client elicitation requests
• New data structures: McpTaskStatus enum, McpTaskInfo, McpResourceSubscription, McpResourceTemplateInfo, McpProgressInfo, McpPendingRequest, McpCancellationInfo

McpServerHandler v1.0

• initial release