Struct McpServer 

pub struct McpServer { /* private fields */ }

An HTTP server that implements the MCP protocol (2024-11-05 to 2025-11-25).

Register tools, resources, and prompts with the builder methods, then pass the server to [Server::run] (or [Server::run_tls]) as an Application. Requests that do not match the MCP endpoint fall through to the built-in App controller chain.

Implementations

impl McpServer

pub fn request_state_key(self, key: impl AsRef<[u8]>) -> Self

The key that signs requestState (MCP 2026-07-28 multi round-trip requests). Random per process by default; give replicas behind a load balancer the same key, so a retry may land on any of them.

pub fn cache_hints(self, ttl_ms: u64, public: bool) -> Self

The caching hints on cacheable results (MCP 2026-07-28: discovery, lists, resources/read): fresh for ttl_ms, shareable between users (public) or not. Default 0 and private — nothing cached; raise it when the lists don’t vary per caller.

impl McpServer

pub fn task_ttl(self, ttl: Duration) -> Self

How long a task is kept after it starts (default an hour).

pub fn max_running_tasks(self, n: usize) -> Self

How many tasks’ work may run at once (default [DEFAULT_MAX_RUNNING_TASKS]): each holds a thread. Past it, McpContext::start_task answers with an error.

pub fn task_required(self, name: &str) -> Self

Mark the tool name as usable only as a task: a client that didn’t declare the tasks extension gets -32021 instead of the tool running.

impl McpServer

pub fn new(name: impl Into<String>, version: impl Into<String>) -> Self

Create a new McpServer. The default MCP endpoint is POST /mcp.

pub fn session_ttl(self, ttl: Duration) -> Self

Evict a session after it has been idle this long (default 1 hour, DEFAULT_SESSION_TTL). A request with an evicted session’s Mcp-Session-Id gets 404, which tells the client to initialize a new session (MCP Streamable HTTP transport).

pub fn max_sessions(self, n: usize) -> Self

Keep at most n sessions (default DEFAULT_MAX_SESSIONS); a new one past that evicts the least recently used.

pub fn max_sse_clients(self, n: usize) -> Self

Accept at most n open GET /mcp SSE streams (default DEFAULT_MAX_SSE_CLIENTS); another gets 503 Service Unavailable.

pub fn tool_title(self, name: &str, title: impl Into<String>) -> Self

A human-readable title for tool name (title in tools/list, MCP 2025-06-18); name stays the identifier. No effect for an unknown name — register the tool first.

pub fn tool_icon(self, name: &str, icon: McpIcon) -> Self

Add an icon to tool name (icons in tools/list, MCP 2025-11-25).

pub fn tool_output_schema(self, name: &str, schema: &str) -> Self

Declare tool name’s result shape: a JSON Schema object (an object type at the top). Clients may validate the structuredContent the handler returns with McpContent::structured against it.

pub fn tool_annotations(self, name: &str, annotations: ToolAnnotations) -> Self

Set (or replace) the behaviour hints of tool name — e.g. read-only, or destructive — for a tool registered without them.

pub fn title(self, title: impl Into<String>) -> Self

A human-readable server title (serverInfo.title, MCP 2025-06-18).

pub fn icon(self, icon: McpIcon) -> Self

Add a server icon (serverInfo.icons, MCP 2025-11-25).

pub fn session_count(&self) -> usize

Number of live sessions (for metrics and tests).

pub fn page_size(self, n: usize) -> Self

Cap tools/list, resources/list, and prompts/list to at most n items per response, enabling cursor-based pagination: a response with more items remaining includes "nextCursor", an opaque string the client echoes back as params.cursor on its next call to get the next page. n is clamped to a minimum of 1.

Without calling this, every registered tool/resource/prompt is returned in a single response — the default, and the only behavior before pagination existed.

use rust_web_server::mcp::McpServer;

let server = McpServer::new("my-server", "1.0").page_size(50);

pub fn notify(&self, method: &str, params_json: Option<&str>)

Push a JSON-RPC notification (no id — fire-and-forget, per the spec) to every client currently connected to the GET /mcp SSE stream, framed as an SSE data: event.

params_json, if given, must already be a valid JSON value (usually an object) — it’s spliced in verbatim, not escaped or re-serialized.

Never blocks: a client whose event buffer is full (not reading fast enough) is treated the same as a disconnected one and dropped from the broadcast list, same as notify would drop it anyway.

use rust_web_server::mcp::McpServer;

let server = McpServer::new("my-server", "1.0");
server.notify("notifications/message", Some(r#"{"level":"info","data":"hello"}"#));

pub fn notify_resource_updated(&self, uri: &str)

Push notifications/resources/updated for uri to every session that called resources/subscribe for it — the mechanism behind live-updating resource panels (e.g. Claude Desktop watching a config file or a dashboard resource for changes). Call this from wherever your application actually changes the underlying data a resource represents (a file watcher, a webhook handler, a database trigger poll, …).

A no-op if nobody has subscribed to uri — including if every subscriber’s GET /mcp SSE connection has since disconnected (pruned the same way Self::notify prunes dead broadcast clients, but the subscriptions bookkeeping for uri itself is untouched either way; only Self::do_resource_unsubscribe removes that).

use rust_web_server::mcp::McpServer;

let server = McpServer::new("my-server", "1.0");
// Elsewhere, e.g. after reloading a watched config file:
server.notify_resource_updated("config://main");

pub fn logging_enabled(self) -> Self

Deprecated by MCP 2026-07-28 (SEP-2577): Logging keeps working with clients that use it, for at least twelve months, but new servers shouldn’t rely on it.

Advertise the logging capability ("logging":{}) in initialize’s response, so clients know they can call logging/setLevel and expect notifications/message log entries over the GET /mcp SSE stream.

This only changes what’s advertised — Self::log pushes log entries regardless of whether this was called, same as Self::notify works unconditionally. A spec-honest client simply wouldn’t send logging/setLevel in the first place without seeing the capability.

use rust_web_server::mcp::McpServer;

let server = McpServer::new("my-server", "1.0").logging_enabled();

pub fn log(&self, level: LogLevel, logger: Option<&str>, data_json: &str)

Deprecated by MCP 2026-07-28 (SEP-2577): Logging keeps working with clients that use it, for at least twelve months, but new servers shouldn’t rely on it.

Push a notifications/message log entry to every client connected to the GET /mcp SSE stream, if level is at or above the level most recently set via a client’s logging/setLevel request (or LogLevel::Debug — i.e. every level — if none has been set yet).

data_json must already be a valid JSON value (the spec allows any type here, not just an object — a plain string is fine) — it’s spliced in verbatim, not escaped or re-serialized. logger, if given, identifies the log’s source (e.g. a module or subsystem name) and is escaped automatically.

use rust_web_server::mcp::{LogLevel, McpServer};

let server = McpServer::new("my-server", "1.0").logging_enabled();
server.log(LogLevel::Warning, Some("database"), r#""connection pool exhausted""#);

pub fn register_tool<F>( &self, name: &str, description: &str, input_schema: &str, handler: F, )

where F: Fn(&str) -> Result<McpContent, String> + Send + Sync + 'static,

Register a callable tool at runtime, exactly like Self::tool but without needing to own the server (and usable after it’s already serving requests). Pushes notifications/tools/list_changed.

use rust_web_server::mcp::{McpContent, McpServer};

let server = McpServer::new("my-server", "1.0");

// Later, from any thread holding a clone of `server`:
server.register_tool("refresh_cache", "Reload the in-memory cache", "{}", |_args| {
    Ok(McpContent::text("cache refreshed"))
});
let existed = server.remove_tool("refresh_cache");
assert!(existed);

pub fn register_async_tool<F, Fut>( &self, name: &str, description: &str, input_schema: &str, handler: F, )

where F: Fn(&str) -> Fut + Send + Sync + 'static, Fut: Future<Output = Result<McpContent, String>> + Send + 'static,

Register an async fn tool handler at runtime, exactly like Self::async_tool but usable after the server is already serving requests. Requires the http2 feature — see async_tool’s docs for the async-to-sync bridging details.

pub fn remove_tool(&self, name: &str) -> bool

Remove a previously-registered tool by name — a sync tool registered via Self::tool/Self::register_tool, or (with the http2 feature) an async one via Self::async_tool/Self::register_async_tool; both collections are checked. Returns true if a tool with that name existed in either and was removed. Pushes notifications/tools/list_changed only when something was actually removed.

pub fn register_resource<F>( &self, uri_template: &str, name: &str, description: &str, handler: F, )

where F: Fn(&str) -> Result<McpContent, String> + Send + Sync + 'static,

Register a readable resource at runtime, exactly like Self::resource. Pushes notifications/resources/list_changed.

pub fn remove_resource(&self, uri_template: &str) -> bool

Remove a previously-registered resource by its exact uri_template (the same string passed to Self::register_resource/Self::resource, not a concrete URI). Returns true if it existed. Pushes notifications/resources/list_changed only when something was removed.

pub fn register_prompt<F>(&self, name: &str, description: &str, handler: F)

where F: Fn(&str) -> Result<Vec<PromptMessage>, String> + Send + Sync + 'static,

Register a prompt template at runtime, exactly like Self::prompt (no argument definitions — use Self::remove_prompt + Self::register_prompt if you need to change a prompt’s arguments later; there is no dynamic equivalent of Self::prompt_with_args). Pushes notifications/prompts/list_changed.

pub fn remove_prompt(&self, name: &str) -> bool

Remove a previously-registered prompt by name. Returns true if it existed. Pushes notifications/prompts/list_changed only when something was removed.

pub fn require_bearer(self, token: impl Into<String>) -> Self

Require a bearer token on every request to the MCP endpoint.

The client must send Authorization: Bearer <token>. Requests with a missing or wrong token receive 401 Unauthorized before any JSON-RPC processing occurs.

Store the token in an environment variable — never hard-code it:

use rust_web_server::app::App;
use rust_web_server::core::New;

let app = App::new()
    .mcp("my-server", "1.0")
    .require_bearer(std::env::var("MCP_TOKEN").expect("MCP_TOKEN not set"));

Claude Desktop config:

{ "mcpServers": { "my-server": {
    "url": "http://localhost:7878/mcp",
    "headers": { "Authorization": "Bearer <token>" }
}}}

An empty token refuses every request (fails closed) rather than accepting an empty Authorization: Bearer (since 17.113.1). Tokens are compared in constant time.

pub fn require_bearer_tokens<I, T, N>(self, tokens: I) -> Self

where I: IntoIterator<Item = (T, N)>, T: Into<String>, N: Into<String>,

Accept several bearer tokens, each naming a caller: a request with Authorization: Bearer <token> is that caller, and handlers see {"sub":"<identity>"} as McpContext::auth_claims — what Self::tool_filter and the gateway decide by. Any other token gets 401. Combines with Self::require_bearer (whose token carries no identity); OAuth ([Self::require_oauth]) replaces both. Empty tokens never match; tokens are compared in constant time.

use rust_web_server::mcp::McpServer;

let server = McpServer::new("my-server", "1.0")
    .require_bearer_tokens([("token-for-alice", "alice"), ("token-for-ci", "ci")]);

pub fn tool_filter<F>(self, allow: F) -> Self

where F: Fn(&McpContext, &str) -> bool + Send + Sync + 'static,

Show and allow only the tools allow(ctx, tool_name) accepts for a request: tools/list leaves the others out, and tools/call answers them as it would an unknown tool. ctx.auth_claims identifies the caller (Self::require_bearer_tokens, [Self::require_oauth]).

use rust_web_server::mcp::McpServer;

let server = McpServer::new("my-server", "1.0")
    .tool_filter(|ctx, tool| !tool.starts_with("admin_") || ctx.auth_claims.as_deref() == Some(r#"{"sub":"root"}"#));

pub fn resource_filter<F>(self, allow: F) -> Self

where F: Fn(&McpContext, &str) -> bool + Send + Sync + 'static,

Which resources a caller may list and read, like Self::tool_filter for tools: allow(ctx, uri_template); a hidden resource is left out of resources/list and resources/templates/list, and reading it answers “not found”.

pub fn prompt_filter<F>(self, allow: F) -> Self

where F: Fn(&McpContext, &str) -> bool + Send + Sync + 'static,

Which prompts a caller may list and get: allow(ctx, name).

pub fn before_tool_call<F>(self, check: F) -> Self

where F: Fn(&McpContext, &str) -> Result<(), String> + Send + Sync + 'static,

Run check before every tools/call that Self::tool_filter allows, with the caller and the tool’s name. Err(message) refuses the call: the client gets a tool error (isError: true) with message, which an agent can read and act on (e.g. “rate limited, retry in 12 s”). Hooks run in the order added; the first refusal wins.

use rust_web_server::mcp::McpServer;

let server = McpServer::new("my-server", "1.0")
    .before_tool_call(|_ctx, tool| if tool == "deploy" { Err("deploys are frozen today".into()) } else { Ok(()) });

pub fn after_tool_call<F>(self, observe: F) -> Self

where F: Fn(&McpContext, &ToolCallRecord<'_>) + Send + Sync + 'static,

Call observe after every tools/call with the caller’s context and a ToolCallRecord: the tool, how it ended (including calls Self::before_tool_call refused and tools Self::tool_filter hides) and how long it took. For audit logs and metrics; it runs on the request’s thread, so keep it quick.

pub fn allowed_origins<I, S>(self, origins: I) -> Self

where I: IntoIterator<Item = S>, S: Into<String>,

Browser origins allowed to call the MCP endpoint, e.g. ["https://inspector.example.com"]. A request carrying an Origin header that isn’t listed gets 403 (the MCP transport spec requires validating Origin: without it a web page — or a DNS-rebinding attack — can drive a local MCP server from the visitor’s browser). Requests without Origin (CLI and agent clients) are unaffected. Empty by default: no browser origin is allowed (since 17.113.1).

pub fn wrap(self, app: impl Application + Send + Sync + 'static) -> Self

Wrap an existing Application so that non-MCP requests are forwarded to it instead of the built-in App.

Use this when your existing server has custom routes, state, or middleware that you want to keep alongside the MCP endpoint:

use rust_web_server::app::App;
use rust_web_server::mcp::{McpServer, McpContent};
use rust_web_server::response::{Response, STATUS_CODE_REASON_PHRASE};
use rust_web_server::test_client::TestClient;

let existing_app = App::with_state(42u32)
    .get("/api/hello", |_req, _params, _conn, _state| {
        Response::get_response(&STATUS_CODE_REASON_PHRASE.n200_ok, None, None)
    });

let server = McpServer::new("my-app", "1.0")
    .tool("ping", "Ping", "{}", |_| Ok(McpContent::text("pong")))
    .wrap(existing_app);

// Both /mcp and /api/hello are now handled by the same server.
let client = TestClient::new(server);

pub fn at(self, path: impl Into<String>) -> Self

Override the HTTP path for the MCP endpoint (default "/mcp").

pub fn tool<F>( self, name: &str, description: &str, input_schema: &str, handler: F, ) -> Self

where F: Fn(&str) -> Result<McpContent, String> + Send + Sync + 'static,

Register a callable tool.

• name — tool identifier (snake_case recommended)
• description — human-readable description shown to the AI
• input_schema — JSON Schema object for the tool’s arguments
• handler — closure receiving the raw arguments JSON string

The handler returns McpContent on success or an error string. An error is returned to the client as isError: true (not a protocol error).

Use Self::tool_with_context instead if the handler needs the caller’s identity, session, or headers.

pub fn async_tool<F, Fut>( self, name: &str, description: &str, input_schema: &str, handler: F, ) -> Self

where F: Fn(&str) -> Fut + Send + Sync + 'static, Fut: Future<Output = Result<McpContent, String>> + Send + 'static,

Register an async fn tool handler — for a tool whose work is naturally async (an AsyncClient HTTP call, an async database query, awaiting another future) rather than forcing it through a blocking call inside a plain Self::tool handler.

Requires the http2 feature (tokio). tools/call bridges into the handler’s future via [crate::async_bridge::block_on_isolated] — the same mechanism crate::proxy::H2ReverseProxy and crate::async_state::AsyncAppWithState already use to call async code from a synchronous Application::execute — rather than tokio::task::block_in_place, which panics outside a multi_thread runtime; block_on_isolated works under any runtime flavor, including current_thread.

Like Self::tool (not Self::tool_with_context), the handler only receives arguments — there is no async equivalent of tool_with_context or tool_annotated yet.

use rust_web_server::mcp::{McpContent, McpServer};

let server = McpServer::new("my-server", "1.0")
    .async_tool("call_api", "Call an external API", "{}", |_args: &str| async move {
        Ok(McpContent::text("response"))
    });

pub fn tool_annotated<F>( self, name: &str, description: &str, input_schema: &str, annotations: ToolAnnotations, handler: F, ) -> Self

where F: Fn(&str) -> Result<McpContent, String> + Send + Sync + 'static,

Register a callable tool with ToolAnnotations — behavioral hints (read-only, destructive, idempotent, open-world) that MCP clients use to decide whether to warn or confirm before calling it. Otherwise identical to Self::tool — the handler still only receives arguments, not McpContext (there is currently no single builder combining annotations with per-request context; call Self::tool_with_context instead if you need context and don’t need annotations).

use rust_web_server::mcp::{McpContent, McpServer, ToolAnnotations};

let server = McpServer::new("my-server", "1.0")
    .tool_annotated(
        "delete_file",
        "Delete a file from disk",
        r#"{"type":"object","properties":{"path":{"type":"string"}},"required":["path"]}"#,
        ToolAnnotations {
            destructive_hint: Some(true),
            read_only_hint: Some(false),
            idempotent_hint: Some(true), // deleting twice = deleting once
            ..Default::default()
        },
        |_args| Ok(McpContent::text("deleted")),
    );

pub fn tool_with_context<F>( self, name: &str, description: &str, input_schema: &str, handler: F, ) -> Self

where F: Fn(McpContext, &str) -> Result<McpContent, String> + Send + Sync + 'static,

Register a callable tool whose handler also receives McpContext — caller identity/session info derived from this request’s headers and whatever clientInfo this session sent at initialize time.

Same name/description/input_schema semantics as Self::tool; the only difference is the handler’s first parameter.

use rust_web_server::mcp::{McpContent, McpServer};

let server = McpServer::new("my-server", "1.0")
    .tool_with_context(
        "whoami",
        "Report the caller's client info",
        "{}",
        |ctx, _args| {
            let name = ctx.client_name.as_deref().unwrap_or("unknown client");
            Ok(McpContent::text(format!("Called by {name}")))
        },
    );

pub fn resource<F>( self, uri_template: &str, name: &str, description: &str, handler: F, ) -> Self

where F: Fn(&str) -> Result<McpContent, String> + Send + Sync + 'static,

Register a readable resource.

uri_template uses {param} placeholders, e.g. "user://{id}". The handler receives the full concrete URI string.

pub fn prompt<F>(self, name: &str, description: &str, handler: F) -> Self

where F: Fn(&str) -> Result<Vec<PromptMessage>, String> + Send + Sync + 'static,

Register a prompt template.

The handler receives the raw arguments JSON string and returns a list of PromptMessage values.

pub fn prompt_with_args<F>( self, name: &str, description: &str, args: Vec<PromptArgDef>, handler: F, ) -> Self

where F: Fn(&str) -> Result<Vec<PromptMessage>, String> + Send + Sync + 'static,

Register a prompt template with explicit argument definitions.

pub fn prompt_with_context<F>( self, name: &str, description: &str, args: Vec<PromptArgDef>, handler: F, ) -> Self

where F: Fn(McpContext, &str) -> Result<PromptReply, String> + Send + Sync + 'static,

Self::prompt_with_args whose handler also gets the request’s McpContext and may answer PromptReply::InputRequired to ask the client for input first (MCP 2026-07-28).

pub fn completion<F>(self, ref_type: &str, ref_name: &str, handler: F) -> Self

where F: Fn(&str, &str) -> Result<Vec<String>, String> + Send + Sync + 'static,

Register an argument-completion provider for one named argument of a tool or prompt, so clients like Cursor and VS Code can offer autocomplete while the user fills in that argument.

ref_type is "tool" or "prompt" — matched against the incoming completion/complete request’s ref.type ("ref/tool"/"ref/prompt" on the wire) with the "ref/" prefix stripped. ref_name is the tool or prompt name this applies to. The handler receives the argument’s name and whatever partial value the user has typed so far, and returns candidate completion strings (or an error, mapped to a JSON-RPC INVALID_PARAMS response).

initialize advertises the completions capability automatically once at least one .completion() has been registered — there’s no separate opt-in flag to remember.

use rust_web_server::mcp::McpServer;

let server = McpServer::new("my-server", "1.0")
    .completion("tool", "deploy", |arg_name, _partial| {
        match arg_name {
            "region" => Ok(vec!["us-east-1".to_string(), "eu-west-1".to_string()]),
            _ => Ok(vec![]),
        }
    });

pub fn handle_request(&self, body: &str) -> Response

Process a raw JSON-RPC body and return an HTTP response.

Equivalent to Self::handle_request_with_context with an empty McpContext — tool handlers registered via Self::tool_with_context will see every field as None. Prefer calling through Application::execute (i.e. actually serving HTTP requests) when you need real per-request context; this method exists for calling the JSON-RPC layer directly, e.g. in tests.

pub fn handle_request_with_context( &self, body: &str, ctx: McpContext, ) -> Response

Process a raw JSON-RPC body with an explicit McpContext and return an HTTP response. Self::execute calls this with a context built from the request’s headers and this session’s stored clientInfo; Self::handle_request calls this with an empty context.

On a successful initialize, this mints a new session id (reusing crate::request_id::generate_request_id’s ID generator), records params.clientInfo under it, and returns the id in an Mcp-Session-Id response header — the client is expected to echo that header back on subsequent requests so later tools/calls in the same session can look their clientInfo back up.

Trait Implementations

impl Application for McpServer

fn runs_inline(&self, request: &Request, connection: &ConnectionInfo) -> bool

MCP calls run tool handlers (user code): never inline. Other requests go to the fallback app, which decides.

fn streams_body(&self, request: &Request, connection: &ConnectionInfo) -> bool

MCP requests are JSON-RPC read whole; other paths: the wrapped app.

fn execute( &self, request: &Request, connection: &ConnectionInfo, ) -> Result<Response, String>

Receives a parsed request and returns a fully-built response. Walk your controller list with is_matching / process and return the first match.

fn execute_async<'a>( &'a self, request: &'a Request, connection: &'a ConnectionInfo, ) -> Option<AsyncResponse<'a>>

An asynchronous version of execute for this request, when the application has one: the async servers await it on the connection’s task instead of tying up a blocking-pool thread while it waits (the config-driven proxy uses this to wait for a backend without holding a thread). None (the default) means “use execute”. Wrappers return Some only when they add no synchronous work of their own.

impl Clone for McpServer

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.