Crate tower_mcp

Expand description

§tower-mcp

Tower-native Model Context Protocol (MCP) implementation for Rust.

This crate provides a composable, middleware-friendly approach to building MCP servers and clients using the Tower service abstraction.

§Philosophy

Unlike framework-style MCP implementations, tower-mcp treats MCP as just another protocol that can be served through Tower’s Service trait. This means:

Standard tower middleware (tracing, metrics, rate limiting, auth) just works
Same service can be exposed over multiple transports (stdio, HTTP, WebSocket)
Easy integration with existing tower-based applications (axum, tonic, etc.)

§Familiar to axum Users

If you’ve used axum, tower-mcp’s API will feel familiar. We’ve adopted axum’s patterns for a consistent Rust web ecosystem experience:

Extractor pattern: Tool handlers use extractors like extract::State<T>, extract::Json<T>, and extract::Context - just like axum’s request extractors
Router composition: McpRouter::merge() and McpRouter::nest() work like axum’s router methods for combining routers
Per-route middleware: Apply Tower layers to individual tools, resources, or prompts via .layer() on builders
Builder pattern: Fluent builders for tools, resources, and prompts

use std::sync::Arc;
use tower_mcp::{ToolBuilder, CallToolResult};
use tower_mcp::extract::{State, Json, Context};
use schemars::JsonSchema;
use serde::Deserialize;

#[derive(Clone)]
struct AppState { db_url: String }

#[derive(Deserialize, JsonSchema)]
struct SearchInput { query: String }

// Looks just like an axum handler!
let tool = ToolBuilder::new("search")
    .title("Search Database")
    .description("Search the database")
    .extractor_handler(
        Arc::new(AppState { db_url: "postgres://...".into() }),
        |State(app): State<Arc<AppState>>,
         ctx: Context,
         Json(input): Json<SearchInput>| async move {
            ctx.report_progress(0.5, Some(1.0), Some("Searching...")).await;
            Ok(CallToolResult::text(format!("Found results for: {}", input.query)))
        },
    )
    .build();

§Quick Start: Server

Build an MCP server with tools, resources, and prompts:

use tower_mcp::{BoxError, McpRouter, ToolBuilder, CallToolResult, StdioTransport};
use schemars::JsonSchema;
use serde::Deserialize;

#[derive(Debug, Deserialize, JsonSchema)]
struct GreetInput {
    name: String,
}

#[tokio::main]
async fn main() -> Result<(), BoxError> {
    // Define a tool
    let greet = ToolBuilder::new("greet")
        .title("Greet")
        .description("Greet someone by name")
        .handler(|input: GreetInput| async move {
            Ok(CallToolResult::text(format!("Hello, {}!", input.name)))
        })
        .build();

    // Create router and run over stdio
    let router = McpRouter::new()
        .server_info("my-server", "1.0.0")
        .tool(greet);

    StdioTransport::new(router).run().await?;
    Ok(())
}

§Quick Start: Client

Connect to an MCP server and call tools:

use tower_mcp::BoxError;
use tower_mcp::client::{McpClient, StdioClientTransport};

#[tokio::main]
async fn main() -> Result<(), BoxError> {
    // Connect to server
    let transport = StdioClientTransport::spawn("my-mcp-server", &[]).await?;
    let client = McpClient::connect(transport).await?;

    // Initialize and list tools
    client.initialize("my-client", "1.0.0").await?;
    let tools = client.list_tools().await?;

    // Call a tool
    let result = client.call_tool("greet", serde_json::json!({"name": "World"})).await?;
    println!("{:?}", result);

    Ok(())
}

§Key Types

§Server

McpRouter - Routes MCP requests to tools, resources, and prompts
ToolBuilder - Builder for defining tools with type-safe handlers
ResourceBuilder - Builder for defining resources
PromptBuilder - Builder for defining prompts
StdioTransport - Stdio transport for CLI servers
McpAppResourceBuilder - Typed ui:// resources for MCP Apps (requires mcp-apps)

§Client

McpClient - Client for connecting to MCP servers
StdioClientTransport - Spawn and connect to server subprocesses

§Protocol

CallToolResult - Tool execution result with content
ReadResourceResult - Resource read result
GetPromptResult - Prompt expansion result
Content - Text, image, audio, or resource content

§Released 2026-07-28 protocol (requires `protocol-2026-07-28`)

stateless::StatelessRequestMeta - Per-request _meta carrying protocol version, client identity, and client capabilities for sessionless 2026-07-28 requests
RequestOutcome and InputRequiredResult - SEP-2322 Multi Round-Trip Request results
RequestStateCodec - Expiring, integrity-protected continuation state
McpClient::discover - Sessionless client discovery with per-request metadata, runtime version selection, SEP-2243 headers, and bounded MRTR auto-driving
McpClient::listen_subscriptions - Long-lived, correlated notification streams with typed acknowledgments and transport-specific cancellation

§Feature Flags

full - Enable all optional features
http - HTTP/SSE transport for web servers (adds axum, hyper)
websocket - WebSocket transport for bidirectional communication
childproc - Child process transport for subprocess management
oauth - OAuth 2.1 resource server support (JWT validation, metadata endpoint; requires http)
jwks - JWKS endpoint fetching for remote key sets (requires oauth)
testing - Test utilities (TestClient) for ergonomic MCP server testing
dynamic-tools - Runtime registration/deregistration of tools, prompts, and resources via DynamicToolRegistry, DynamicPromptRegistry, DynamicResourceRegistry, DynamicResourceTemplateRegistry
proxy - Multi-server aggregation proxy (McpProxy)
http-client - HTTP client transport for connecting to remote MCP servers
oauth-client - OAuth client support: authorization code with PKCE, registration, refresh and scope escalation; client credentials; discovery; and custom token providers (requires http-client)
macros - Optional proc macros (#[tool_fn], #[prompt_fn], #[resource_fn], #[resource_template_fn])
mcp-apps - Typed server support for the stable MCP Apps extension. Runtime advertisement remains explicit through McpRouter::with_mcp_apps.
protocol-2026-07-28 - Compile the released 2026-07-28 implementation. Use ProtocolSupport to select enabled versions at runtime. Enables version-gated sessionless dispatch, server/discover RPC, per-request _meta via stateless::StatelessRequestMeta, subscriptions/listen, SEP-2322 MRTR handlers, and the discover-based McpClient path.
stateless - Compatibility alias for the former 2026 protocol feature name.

For complete server and client setup, registration and persistence policy, and a production checklist, see the guides::oauth.

§Task-oriented Guides

guides::client — transport selection, lifecycle, callbacks, requests, caching, retries, and shutdown.
guides::deployment — mounting, reverse proxies, origin/host validation, sessions, scaling, timeouts, middleware order, health, and graceful shutdown.
guides::protocol_versions — compile-time availability, runtime allowlists, lifecycle differences, interoperability, and upgrades.
guides — OAuth, MCP Apps, and the complete task-oriented guide index.
Examples index — runnable server, client, transport, middleware, OAuth, and extension patterns.

§Middleware Placement Guide

tower-mcp supports Tower middleware at multiple levels. Choose based on scope:

Level	Method	Scope	Use Cases
Transport	`StdioTransport::layer()`, `HttpTransport::layer()`	All MCP requests	Global timeout, rate limit, metrics
axum	`.into_router().layer()`	HTTP layer only	CORS, compression, request logging
Per-tool	`ToolBuilder::...layer()`	Single tool	Tool-specific timeout, concurrency
Per-resource	`ResourceBuilder::...layer()`	Single resource	Caching, read timeout
Per-prompt	`PromptBuilder::...layer()`	Single prompt	Generation timeout

§Decision Tree

Where should my middleware go?
│
├─ Affects ALL MCP requests?
│  └─ Yes → Transport: StdioTransport::layer(), HttpTransport::layer(), or WebSocketTransport::layer()
│
├─ HTTP-specific (CORS, compression, headers)?
│  └─ Yes → axum: transport.into_router().layer(...)
│
├─ Only one specific tool?
│  └─ Yes → Per-tool: ToolBuilder::...handler(...).layer(...)
│
├─ Only one specific resource?
│  └─ Yes → Per-resource: ResourceBuilder::...handler(...).layer(...)
│
└─ Only one specific prompt?
   └─ Yes → Per-prompt: PromptBuilder::...handler(...).layer(...)

§Example: Layered Timeouts

use std::time::Duration;
use tower::timeout::TimeoutLayer;
use tower_mcp::{McpRouter, ToolBuilder, CallToolResult, HttpTransport};
use schemars::JsonSchema;
use serde::Deserialize;

#[derive(Debug, Deserialize, JsonSchema)]
struct SearchInput { query: String }

// This tool gets a longer timeout than the global default
let slow_search = ToolBuilder::new("slow_search")
    .description("Thorough search (may take a while)")
    .handler(|input: SearchInput| async move {
        // ... slow operation ...
        Ok(CallToolResult::text("results"))
    })
    .layer(TimeoutLayer::new(Duration::from_secs(60)))  // 60s for this tool
    .build();

let router = McpRouter::new()
    .server_info("example", "1.0.0")
    .tool(slow_search);

// Global 30s timeout for all OTHER requests
let transport = HttpTransport::new(router)
    .layer(TimeoutLayer::new(Duration::from_secs(30)));

In this example:

slow_search tool has a 60-second timeout (per-tool layer)
All other MCP requests have a 30-second timeout (transport layer)
The per-tool layer is inner to the transport layer

§Layer Ordering

Layers wrap from outside in. The first layer added is the outermost:

Request → [Transport Layer] → [Per-tool Layer] → Handler → Response

For per-tool/resource/prompt, chained .layer() calls also wrap outside-in:

ToolBuilder::new("api")
    .handler(...)
    .layer(TimeoutLayer::new(...))      // Outer: timeout checked first
    .layer(ConcurrencyLimitLayer::new(5)) // Inner: concurrency after timeout
    .build()

§Full Example

See examples/tool_middleware.rs for a complete example demonstrating:

Different timeouts per tool
Concurrency limiting for expensive operations
Multiple layers combined on a single tool

§Advanced Features

§Sampling (LLM Requests)

Tools can request LLM completions from the client via RequestContext::sample(). This enables AI-assisted tools like “suggest a query” or “analyze results”:

use tower_mcp::{ToolBuilder, CallToolResult, CreateMessageParams, SamplingMessage};
use tower_mcp::extract::Context;

let tool = ToolBuilder::new("suggest")
    .description("Get AI suggestions")
    .extractor_handler(|ctx: Context| async move {
        if !ctx.can_sample() {
            return Ok(CallToolResult::error("Sampling not available"));
        }

        let params = CreateMessageParams::new()
            .message(SamplingMessage::user("Suggest 3 search queries for: rust async"))
            .max_tokens(200);

        let result = ctx.sample(params).await?;
        let text = result.first_text().unwrap_or("No response");
        Ok(CallToolResult::text(text))
    })
    .build();

§Elicitation (User Input)

Tools can request user input via forms using RequestContext::elicit_form() or the convenience method RequestContext::confirm():

use tower_mcp::{ToolBuilder, CallToolResult};
use tower_mcp::extract::Context;

// Simple confirmation dialog
let delete_tool = ToolBuilder::new("delete")
    .description("Delete a file")
    .extractor_handler(|ctx: Context| async move {
        if !ctx.confirm("Are you sure you want to delete this file?").await? {
            return Ok(CallToolResult::text("Cancelled"));
        }
        // ... perform deletion ...
        Ok(CallToolResult::text("Deleted"))
    })
    .build();

For complex forms, use ElicitFormSchema to define multiple fields.

§Progress Notifications

Long-running tools can report progress via RequestContext::report_progress():

use tower_mcp::{ToolBuilder, CallToolResult};
use tower_mcp::extract::Context;

let process_tool = ToolBuilder::new("process")
    .description("Process items")
    .extractor_handler(|ctx: Context| async move {
        let items = vec!["a", "b", "c", "d", "e"];
        let total = items.len() as f64;

        for (i, item) in items.iter().enumerate() {
            ctx.report_progress(i as f64, Some(total), Some(&format!("Processing {}", item))).await;
            // ... process item ...
        }

        Ok(CallToolResult::text("Done"))
    })
    .build();

§Stateless Mode (2026-07-28, requires `protocol-2026-07-28` + `http`)

The protocol-2026-07-28 feature enables the released 2026-07-28 MCP protocol. In this mode the initialize/initialized handshake is replaced by two new RPCs:

server/discover – stateless capability discovery. Clients that send requests with MCP-Protocol-Version: 2026-07-28 (SEP-2243 header) can call server/discover instead of initialize to learn what the server supports without establishing a session.
subscriptions/listen – client-initiated SSE subscription. A POST of a subscriptions/listen request with MCP-Protocol-Version: 2026-07-28 opens a server-push stream that is not tied to any session, allowing stateless clients to receive notifications. McpClient::listen_subscriptions returns a handle that exposes the accepted filter and subscription ID; dropping or cancelling the handle closes only that request’s response stream.

Per-request client identity and capabilities ride in each request’s _meta object via stateless::StatelessRequestMeta rather than being negotiated once at session open. The MCP-Protocol-Version header value is the version gate: requests carrying exactly 2026-07-28 route through the stateless path; older requests continue through the session-based path unchanged.

use tower_mcp::{McpRouter, HttpTransport};
use tower_mcp::stateless::StatelessConfig;

let router = McpRouter::new().server_info("my-server", "1.0.0");

// Enable stateless mode alongside the session-based path.
let transport = HttpTransport::new(router)
    .stateless(StatelessConfig::new());

The 2026-07-28 implementation is opt-in. Enable the protocol-2026-07-28 Cargo feature to compile it, then use ProtocolSupport to narrow the versions enabled by an individual transport at runtime.

§Router Composition

Combine multiple routers using McpRouter::merge() or McpRouter::nest():

use tower_mcp::McpRouter;

// Create domain-specific routers
let db_router = McpRouter::new()
    .tool(query_tool)
    .tool(insert_tool);

let api_router = McpRouter::new()
    .tool(fetch_tool);

// Nest with prefixes: tools become "db.query", "db.insert", "api.fetch"
let combined = McpRouter::new()
    .server_info("combined", "1.0")
    .nest("db", db_router)
    .nest("api", api_router);

// Or merge without prefixes
let merged = McpRouter::new()
    .merge(db_router)
    .merge(api_router);

§Multi-Server Proxy

Aggregate multiple backend MCP servers behind a single endpoint using McpProxy (requires the proxy feature):

use tower_mcp::proxy::McpProxy;
use tower_mcp::client::StdioClientTransport;

let proxy = McpProxy::builder("my-proxy", "1.0.0")
    .backend("db", StdioClientTransport::spawn("db-server", &[]).await?)
    .await
    .backend("fs", StdioClientTransport::spawn("fs-server", &[]).await?)
    .await
    .build()
    .await?;

// Tools become `db_query`, `fs_read`, etc.
// Serve over any transport -- stdio, HTTP, WebSocket.
GenericStdioTransport::new(proxy).run().await?;

The proxy supports per-backend Tower middleware, notification forwarding, health checks, and request coalescing. See the proxy module for details.

§Production Deployment

See the deployment module for load balancer patterns, session affinity, horizontal scaling with the session_store and event_store traits, reverse proxy configuration (nginx, Caddy, Traefik), observability, and sidecar deployments.

§MCP Specification

This crate implements MCP 2025-11-25 by default and provides an opt-in implementation of the released 2026-07-28 specification: https://modelcontextprotocol.io/specification/2026-07-28

Enable it with protocol-2026-07-28; the legacy stateless feature name remains a compatibility alias. Major final-version work includes:

SEP-2322 – Multi Round-Trip Requests
SEP-2567 – subscriptions/listen SSE endpoint
SEP-2575 – stateless session model, server/discover, per-request _meta
SEP-2243 – strict HTTP headers (Mcp-Method, Mcp-Name, MCP-Protocol-Version)

Re-exports§

pub use apps::MCP_APP_HTML_MIME_TYPE;
pub use apps::MCP_APPS_EXTENSION_ID;
pub use apps::McpAppDomain;
pub use apps::McpAppError;
pub use apps::McpAppHtml;
pub use apps::McpAppResourceBuilder;
pub use apps::McpAppUri;
pub use apps::McpAppsCapabilitySettings;
pub use apps::McpUiPermissions;
pub use apps::McpUiResourceCsp;
pub use apps::McpUiResourceMeta;
pub use apps::McpUiToolMeta;
pub use apps::McpUiToolVisibility;
pub use apps::mcp_app_tool_result;
pub use apps::mcp_apps_extension;
pub use async_task::MemoryTaskStore;
pub use async_task::Task;
pub use async_task::TaskStore;
pub use client::ChannelTransport;
pub use client::ClientHandler;
pub use client::ClientTransport;
pub use client::McpClient;
pub use client::McpClientBuilder;
pub use client::NotificationHandler;
pub use client::StdioClientTransport;
pub use client::HttpClientConfig;
pub use client::HttpClientTransport;
pub use client::MemoryOAuthAuthorizationStateStore;
pub use client::MemoryOAuthClientRegistrationStore;
pub use client::MemoryOAuthTokenStore;
pub use client::OAuthApplicationType;
pub use client::OAuthAuthorizationAction;
pub use client::OAuthAuthorizationFlow;
pub use client::OAuthAuthorizationFlowBuilder;
pub use client::OAuthAuthorizationHandler;
pub use client::OAuthAuthorizationRequest;
pub use client::OAuthAuthorizationServerMetadata;
pub use client::OAuthAuthorizationStart;
pub use client::OAuthAuthorizationStateStore;
pub use client::OAuthClientAssertionRequest;
pub use client::OAuthClientAssertionSigner;
pub use client::OAuthClientCredentials;
pub use client::OAuthClientError;
pub use client::OAuthClientRegistration;
pub use client::OAuthClientRegistrationMethod;
pub use client::OAuthClientRegistrationOptions;
pub use client::OAuthClientRegistrationStore;
pub use client::OAuthDynamicClientRegistration;
pub use client::OAuthHttpBody;
pub use client::OAuthHttpClient;
pub use client::OAuthHttpMethod;
pub use client::OAuthHttpRequest;
pub use client::OAuthHttpResponse;
pub use client::OAuthPendingAuthorization;
pub use client::OAuthPendingAuthorizationState;
pub use client::OAuthRedirectPolicy;
pub use client::OAuthScopeChallenge;
pub use client::OAuthScopeEscalationConfig;
pub use client::OAuthScopeEscalationHandler;
pub use client::OAuthScopeEscalationRequest;
pub use client::OAuthStoredToken;
pub use client::OAuthTokenBinding;
pub use client::OAuthTokenStore;
pub use client::ReqwestOAuthHttpClient;
pub use client::TokenProvider;
pub use client::discover_oauth_authorization_server;
pub use client::resolve_oauth_client_registration;
pub use client::resolve_oauth_client_registration_with_store;
pub use context::ChannelClientRequester;
pub use context::ClientRequester;
pub use context::ClientRequesterHandle;
pub use context::Extensions;
pub use context::NotificationReceiver;
pub use context::NotificationSender;
pub use context::OutgoingRequest;
pub use context::OutgoingRequestReceiver;
pub use context::OutgoingRequestSender;
pub use context::RequestContext;
pub use context::RequestContextBuilder;
pub use context::ServerNotification;
pub use context::outgoing_request_channel;
pub use extension::ExtensionDeclaration;
pub use extension::NegotiatedExtension;
pub use extension::NegotiatedExtensions;
pub use filter::CapabilityFilter;
pub use filter::DenialBehavior;
pub use filter::Filterable;
pub use filter::PromptFilter;
pub use filter::ResourceFilter;
pub use filter::ToolFilter;
pub use jsonrpc::JsonRpcLayer;
pub use jsonrpc::JsonRpcService;
pub use middleware::AuditLayer;
pub use middleware::AuditService;
pub use middleware::McpTracingLayer;
pub use middleware::McpTracingService;
pub use middleware::ToolCallLoggingLayer;
pub use middleware::ToolCallLoggingService;
pub use mrtr::MrtrRequest;
pub use mrtr::RequestStateCodec;
pub use mrtr::RequestStateError;
pub use prompt::MrtrPromptHandler;
pub use prompt::BoxPromptService;
pub use prompt::Prompt;
pub use prompt::PromptBuilder;
pub use prompt::PromptHandler;
pub use prompt::PromptRequest;
pub use registry::DynamicPromptRegistry;
pub use registry::DynamicResourceRegistry;
pub use registry::DynamicResourceTemplateRegistry;
pub use registry::DynamicToolRegistry;
pub use resource::BoxResourceService;
pub use resource::Resource;
pub use resource::ResourceBuilder;
pub use resource::ResourceHandler;
pub use resource::ResourceRequest;
pub use resource::ResourceTemplate;
pub use resource::ResourceTemplateBuilder;
pub use resource::ResourceTemplateHandler;
pub use resource::MrtrResourceHandler;
pub use resource::MrtrResourceTemplateHandler;
pub use router::McpRouter;
pub use router::RouterRequest;
pub use router::RouterResponse;
pub use router::ToolAnnotationsMap;
pub use session::SessionPhase;
pub use session::SessionState;
pub use tool::MrtrToolHandler;
pub use tool::BoxToolService;
pub use tool::GuardLayer;
pub use tool::NoParams;
pub use tool::Tool;
pub use tool::ToolBuilder;
pub use tool::ToolHandler;
pub use tool::ToolRequest;
pub use transport::BidirectionalStdioTransport;
pub use transport::CatchError;
pub use transport::GenericStdioTransport;
pub use transport::StdioTransport;
pub use transport::SyncStdioTransport;
pub use transport::HttpTransport;
pub use transport::SessionHandle;
pub use transport::SessionInfo;
pub use transport::WebSocketTransport;
pub use transport::McpBoxService;
pub use transport::UnixSocketTransport;
pub use transport::ChildProcessConnection;
pub use transport::ChildProcessTransport;
pub use oauth::ScopeEnforcementLayer;
pub use oauth::ScopeEnforcementService;
pub use oauth::JwksError;
pub use oauth::JwksValidator;
pub use oauth::JwksValidatorBuilder;
pub use testing::TestClient;
pub use schemars;

Modules§

apps: Typed server support for the stable MCP Apps extension (SEP-1865).
async_task: Async task management for long-running MCP operations
auth: Authentication middleware helpers for MCP servers
client: MCP Client with bidirectional communication support.
context: Request context for MCP handlers
deployment: Production deployment guide.
error: Error types (re-exported from tower-mcp-types).
event_store: Pluggable storage for SSE events enabling stream resumption.
extension: Protocol extension declarations and runtime negotiation.
extract: Extractor pattern for tool handlers
filter: Session-based capability filtering.
guides: Task-oriented guides for building and operating tower-mcp applications.
inspection: JSON-RPC and exact-revision MCP semantic inspection types re-exported from tower-mcp-types.
jsonrpc: JSON-RPC 2.0 service layer
middleware: MCP-specific tower middleware layers.
mrtr: Server-side helpers for Multi Round-Trip Requests (SEP-2322).
oauth: OAuth 2.1 resource server support for MCP.
prompt: Prompt definition and builder API
protocol: MCP protocol types (re-exported from tower-mcp-types).
proxy: MCP Proxy – aggregate multiple backend MCP servers behind a single endpoint.
registry: Dynamic tool registry for runtime tool (de)registration.
resource: Resource definition and builder API
router: MCP Router - routes requests to tools, resources, and prompts
session: MCP session state management
session_store: Pluggable session storage for HTTP and WebSocket transports.
stateless: Stateless MCP support: SEP-1442 opt-in and automatic 2026-07-28 dispatch
tasks: Final Tasks extension wire types (re-exported from tower-mcp-types).
testing: Test utilities for MCP servers.
tool: Tool definition and builder API
tracing_layer: MCP request tracing middleware.
transport: MCP transport implementations

Structs§

BooleanSchema: Boolean field schema
CallToolParams: Parameters for invoking a tool through tools/call.
CallToolResult: Result of a tool invocation.
CancelTaskParams: Parameters for cancelling a task
CancelledParams: Parameters for cancellation notification.
ClientCapabilities: Features a client can provide or accept.
ClientTasksCancelCapability: Marker capability for client tasks/cancel support
ClientTasksCapability: Legacy 2025-11-25 client capability for async task management.
ClientTasksElicitationCapability: Legacy capability for task-augmented elicitation requests.
ClientTasksElicitationCreateCapability: Legacy task-augmented elicitation marker.
ClientTasksListCapability: Marker capability for client tasks/list support
ClientTasksRequestsCapability: Legacy client capability declaring task-augmented request support.
ClientTasksSamplingCapability: Legacy capability for task-augmented sampling requests.
ClientTasksSamplingCreateMessageCapability: Legacy task-augmented sampling marker.
CompleteParams: Parameters for completion/complete request
CompleteResult: Result of completion/complete request
Completion: Completion suggestions
CompletionArgument: Argument being completed
CompletionContext: Context provided alongside a completion request
CompletionsCapability: Server capability for providing completions
ContentAnnotations: Annotations for content items
CreateMessageParams: Parameters for sampling/createMessage request
CreateMessageResult: Result of sampling/createMessage request
CreateTaskResult: Backwards-compatible task-creation result used by the 2025-11-25 API.
ElicitFormParams: Parameters for form-based elicitation request
ElicitFormSchema: Restricted JSON Schema for elicitation forms.
ElicitResult: Result of an elicitation request
ElicitUrlParams: Parameters for URL-based elicitation request.
ElicitationCapability: Client capability for elicitation (requesting user input)
ElicitationCompleteParams: Parameters for elicitation complete notification.
ElicitationFormCapability: Marker for form-based elicitation support
ElicitationUrlCapability: Marker for URL-based elicitation support
EmptyResult: Empty successful result object ({}).
GetPromptParams: Parameters for rendering a prompt through prompts/get.
GetPromptResult: The result of a prompts/get request.
GetPromptResultBuilder: Builder for constructing GetPromptResult with multiple messages.
GetTaskInfoParams: Parameters for getting task info
GetTaskResultParams: Parameters for getting task result
Implementation: Information about a client or server implementation
InitializeParams: Parameters sent by a client during the legacy initialize handshake.
InitializeResult: Server response to the legacy initialize handshake.
InputRequiredResult: A 2026-07-28 result signalling the server needs more input before it can complete the original request (SEP-2322).
IntegerSchema: Integer field schema
JsonRpcErrorResponse: JSON-RPC 2.0 error response.
JsonRpcNotification: JSON-RPC 2.0 notification (no response expected)
JsonRpcRequest: JSON-RPC 2.0 request.
JsonRpcResultResponse: JSON-RPC 2.0 success response.
ListPromptsParams: Pagination and metadata for a prompts/list request.
ListPromptsResult: One page returned by prompts/list.
ListResourceTemplatesParams: Parameters for listing resource templates
ListResourceTemplatesResult: Result of listing resource templates
ListResourcesParams: Pagination and metadata for a resources/list request.
ListResourcesResult: One page returned by resources/list.
ListRootsParams: Result of a roots/list request from the server.
ListRootsResult: Result of roots/list request
ListTasksParams: Parameters for listing tasks
ListTasksResult: Result of listing tasks
ListToolsParams: Pagination and metadata for a tools/list request.
ListToolsResult: One page returned by tools/list.
LoggingCapability: Logging capability declaration
LoggingMessageParams: Parameters for logging message notification
ModelHint: Hint for model selection
ModelPreferences: Preferences for model selection during sampling
MultiSelectEnumItems: Items definition for multi-select enum
MultiSelectEnumSchema: Multi-select enum schema
NotificationMeta: Subscription meta (_meta) carried by messages delivered on a subscriptions/listen stream.
NumberSchema: Number field schema
ProgressParams: Parameters for progress notification
PromptArgument: One named argument accepted by a prompt template.
PromptDefinition: Prompt metadata returned by prompts/list.
PromptMessage: A role-tagged content block in a rendered prompt.
PromptReference: Reference to a prompt for completion
PromptsCapability: Options advertised for the server’s prompt capability.
ProtocolSupport: Exact, ordered protocol-version allow-list for one runtime component.
ReadResourceParams: Parameters for a resources/read request.
ReadResourceResult: Contents returned by resources/read.
RequestMeta: Request metadata (_meta).
ResourceContent: Content of an embedded resource.
ResourceDefinition: Resource metadata returned by resources/list.
ResourceReference: Reference to a resource for completion
ResourceTemplateDefinition: Definition of a resource template as returned by resources/templates/list
ResourcesCapability: Options advertised for the server’s resource capability.
Root: Represents a root directory or file that the server can operate on.
RootsCapability: Client capability for roots (filesystem access) Capabilities related to filesystem roots.
SamplingCapability: Client support for server-initiated sampling requests.
SamplingContextCapability: Marker capability for context inclusion within sampling
SamplingMessage: Message for sampling request
SamplingTool: Tool definition for use in sampling requests (SEP-1577)
SamplingToolsCapability: Marker capability for tool use within sampling
ServerCapabilities: Features exposed by an MCP server.
SetLogLevelParams: Parameters for setting log level
SingleSelectEnumSchema: Single-select enum schema
StringSchema: String field schema
SubscribeResourceParams: Parameters for a resources/subscribe request.
SubscriptionFilter: Notification types a client opts in to on a subscriptions/listen stream (SEP-2575). Replaces the 2025-11-25 resources/subscribe RPC. The server MUST NOT send a notification type the client did not request.
SubscriptionsAcknowledgedParams: Parameters for a notifications/subscriptions/acknowledged notification: the subset of requested notification types the server will honor.
SubscriptionsListenParams: Parameters for the subscriptions/listen RPC (SEP-2575 / SEP-2567).
SubscriptionsListenResult: Graceful final result of the subscriptions/listen RPC.
SubscriptionsListenResultMeta: Result metadata for a gracefully closed subscriptions/listen request.
TaskObject: Task object matching the MCP 2025-11-25 spec
TaskRequestParams: Legacy 2025-11-25 task-augmentation parameters.
TaskStatusParams: Notification params when task status changes
TasksCancelCapability: Marker capability for tasks/cancel support
TasksCapability: Legacy 2025-11-25 server capability for async task management.
TasksListCapability: Marker capability for tasks/list support
TasksRequestsCapability: Legacy server capability declaring task-augmented request support.
TasksToolsCallCapability: Legacy task-augmented tools/call marker.
TasksToolsRequestsCapability: Legacy capability for task-augmented tool requests.
ToolAnnotations: Annotations describing tool behavior for trust and safety. Clients MUST consider these untrusted unless the server is trusted.
ToolChoice: Tool choice mode for sampling requests (SEP-1577)
ToolDefinition: Tool definition as returned by tools/list
ToolError: Tool execution error with context
ToolExecution: Legacy 2025-11-25 task execution metadata for a tool definition.
ToolIcon: Icon for tool display in user interfaces
ToolsCapability: Options advertised for the server’s tool capability.
UnsubscribeResourceParams: Parameters for a resources/unsubscribe request.
UpdateTaskParams: Parameters for the SEP-2663 tasks/update request.

Enums§

CompletionReference: Reference for completion - either a prompt or resource reference
Content: Content types for tool results, resources, and prompts.
ContentRole: Role indicating who content is intended for.
ElicitAction: User action in response to elicitation
ElicitFieldValue: Value from an elicitation form field
ElicitMode: Elicitation mode
ElicitRequestParams: Elicitation request parameters (union of form and URL modes)
Error: tower-mcp error type
IconTheme: Icon theme context
IncludeContext: Context inclusion mode for sampling
InputRequest: A single server-initiated request the client must fulfil during a Multi Round-Trip Request (SEP-2322). Serialized adjacently as {method, params}, mirroring the JSON-RPC request embedded in an InputRequests map.
InputResponse: A single client response to a server-initiated InputRequest (SEP-2322). Untagged: the wire value is the bare result object, correlated to its request by its key in the InputResponses map.
JsonRpcMessage: JSON-RPC 2.0 message - can be a single request or a batch
JsonRpcResponse: JSON-RPC 2.0 response (either success or error).
JsonRpcResponseMessage: JSON-RPC 2.0 response message - can be a single response or a batch
LogLevel: Log severity levels following RFC 5424 (syslog)
McpNotification: High-level MCP notification (parsed from JSON-RPC)
McpRequest: High-level MCP request (parsed from JSON-RPC)
McpResponse: High-level MCP response
PrimitiveSchemaDefinition: Primitive schema definition for form fields
ProgressToken: Progress token - can be string or number
PromptRole: Conversation role assigned to a rendered prompt message.
ProtocolSupportError: Error returned for an invalid runtime protocol configuration.
RequestId: Request ID - can be string or number per JSON-RPC spec
RequestOutcome: Result of a request that may either complete or ask the client for additional input (SEP-2322).
ResultType: The type discriminator carried by a 2026-07-28 result (SEP-2322).
SamplingContent: Content types for sampling messages
SamplingContentOrArray: Content that can be either a single item or an array
TaskStatus: Status of an async task
TaskSupportMode: Task support mode for tool execution

Constants§

COMPILED_PROTOCOL_VERSIONS: Protocol versions compiled into this build, in preference order.
RESULT_TYPE_TASK: SEP-2322 / SEP-2663 resultType discriminator value for task results.
TASKS_EXTENSION_ID: Reverse-DNS identifier for the SEP-2663 tasks extension.

Traits§

ResultExt: Extension trait for converting errors into tower-mcp tool errors.

Functions§

is_protocol_version_compiled: Returns whether a protocol implementation is present in this build.

Type Aliases§

BoxError: Type-erased error type used for middleware composition.
InputRequests: Map of server-initiated requests the client must fulfil, keyed by server-assigned identifiers (SEP-2322).
InputResponses: Map of client responses to InputRequests, keyed by the same identifiers (SEP-2322).
Result: Result type alias for tower-mcp
TaskInfoDeprecated: Backwards-compatible alias for TaskObject
TaskStatusChangedParams: Backwards-compatible alias

Attribute Macros§

prompt_fn: Generates a prompt constructor function from an async handler.
resource_fn: Generates a static resource constructor function from an async handler.
resource_template_fn: Generates a resource template constructor function from an async handler.
tool_fn: Generates a tool constructor function from an async handler.

Crate tower_mcp

Crate tower_mcp Copy item path

§tower-mcp

§Philosophy

§Familiar to axum Users

§Quick Start: Server

§Quick Start: Client

§Key Types

§Server

§Client

§Protocol

§Released 2026-07-28 protocol (requires protocol-2026-07-28)

§Feature Flags

§Task-oriented Guides

§Middleware Placement Guide

§Decision Tree

§Example: Layered Timeouts

§Layer Ordering

§Full Example

§Advanced Features

§Sampling (LLM Requests)

§Elicitation (User Input)

§Progress Notifications

§Stateless Mode (2026-07-28, requires protocol-2026-07-28 + http)

§Router Composition

§Multi-Server Proxy

§Production Deployment

§MCP Specification

Re-exports§

Modules§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Attribute Macros§

Crate tower_mcp

§Released 2026-07-28 protocol (requires `protocol-2026-07-28`)

§Stateless Mode (2026-07-28, requires `protocol-2026-07-28` + `http`)