Module mcp 

Model Context Protocol (MCP) server — HTTP Streamable HTTP transport.

McpServer implements Application so it can be passed directly to [Server::run]. Unmatched requests fall through to the built-in App controller chain (static files, health probes, etc.).

Quick start

use rust_web_server::server::Server;
use rust_web_server::mcp::{McpServer, McpContent, PromptMessage};
let mcp = McpServer::new("my-server", "1.0")
    // A tool: callable by the AI, like a function
    .tool(
        "echo",
        "Echo text back",
        r#"{"type":"object","properties":{"text":{"type":"string"}},"required":["text"]}"#,
        |args| {
            let text = rust_web_server::mcp::extract_arg(args, "text")
                .unwrap_or_else(|| "(nothing)".to_string());
            Ok(McpContent::text(text))
        },
    )
    // A resource: data the AI can read by URI
    .resource(
        "docs://{topic}",
        "Documentation",
        "Return documentation for a topic",
        |uri| Ok(McpContent::text(format!("Documentation for: {uri}"))),
    )
    // A prompt template: reusable message structures
    .prompt(
        "summarize",
        "Summarize the given text",
        |args| {
            let text = rust_web_server::mcp::extract_arg(args, "text")
                .unwrap_or_else(|| "some text".to_string());
            Ok(vec![PromptMessage::user(format!("Please summarize: {text}"))])
        },
    );

// let (listener, pool) = Server::setup().unwrap();
// Server::run(listener, pool, mcp);

MCP endpoint

All JSON-RPC messages are sent as POST /mcp (override with .at()). The server implements the MCP 2024-11-05 specification.

GET /mcp opens a Server-Sent Events stream for server → client push — see McpServer::notify and the module docs’ SSE section below.

SSE streaming transport

A client that sends GET /mcp (instead of POST) gets back a text/event-stream response that stays open indefinitely. Call McpServer::notify from anywhere (a background thread, another request’s handler, …) to push a JSON-RPC notification to every currently-connected SSE client:

use rust_web_server::mcp::McpServer;

let server = McpServer::new("my-server", "1.0");
// Elsewhere, e.g. after some background job finishes:
server.notify("notifications/message", Some(r#"{"level":"info","data":"job done"}"#));

Idle connections receive a : keep-alive SSE comment every 15 seconds so intermediate proxies don’t time them out; this doubles as the mechanism that detects a client has disconnected (the next write attempt fails and the connection is dropped). A client whose event buffer fills up (32 pending frames, unconsumed) is treated the same as a disconnected one and dropped from the broadcast list — McpServer::notify never blocks the calling thread waiting on a slow reader.

This transport is only wired up for the plain HTTP/1.1 path (Server::run/Server::process) — same scope as Response::stream_pipe generally, which the HTTP/2 (h2_handler) and HTTP/3 (h3_handler) handlers don’t yet support for any response, not just this one.

Environment variables

None — configure the server programmatically via the builder.

Structs

McpContent

Content returned by tool and resource handlers.

McpContext

Per-request context passed to tool handlers registered via McpServer::tool_with_context — caller identity and session info that a plain Fn(&str) -> ... tool handler has no way to see.

McpRoot

One filesystem root a client has access to, returned by McpContext::list_roots — a workspace directory, a mounted volume, or similar. uri is typically a file:// URI per spec.

McpServer

An HTTP server that implements the MCP 2024-11-05 protocol.

PromptArgDef

Argument definition for a prompt template.

PromptMessage

A single message in a prompt response.

SamplingRequest

A request to ask the connected MCP client to run LLM inference (“sampling”) — build one and pass it to McpContext::sample.

SamplingResponse

The client’s answer to a SamplingRequest, returned by McpContext::sample.

ToolAnnotations

Behavioral hints for a tool, per the MCP 2025-03-26 spec’s tool annotations. Clients (Claude Desktop and others) use these to decide whether to warn or ask for confirmation before calling a tool — e.g. skip confirmation for a read-only tool, or warn before a destructive one.

Enums

LogLevel

RFC 5424 syslog severity levels, as used by the MCP logging/setLevel request and notifications/message log entries — ordered from most to least verbose so level < min_level comparisons work directly (this relies on declaration order matching severity order; don’t reorder the variants).

Functions

extract_arg

Extract a string argument from a tool/prompt arguments JSON object.