rust-mcp-sdk

A high-performance, asynchronous Rust toolkit for building MCP servers and clients.

Documentation · Tutorials · Examples · Upgrade Guide · Changelog Contributing · Report a bug · Request a Feature

This SDK fully implements the MCP 2026-07-28 stateless protocol and passes 100% of official MCP conformance tests (110/110 server, 440/440 client).

rust-mcp-sdk provides the necessary components for developing both servers and clients in the MCP ecosystem. It leverages the rust-mcp-schema crate for type-safe schema objects and includes powerful procedural macros.

Focus on your application logic, rust-mcp-sdk handles the protocol, transports, and the rest.

⚠️ Version notice: This is rust-mcp-sdk 2.x, implementing the new MCP 2026-07-28 (stateless) specification. For the previous MCP 2025-11-25 specification, use rust-mcp-sdk 1.x:

rust-mcp-sdk = "1"

See the upgrade guide to migrate from 1.x to 2.0.

Version matrix:

SDK version	Protocol	Branch
2.0	MCP 2026-07-28 (stateless)	main
1.x (LTS)	MCP 2025-11-25	release-1.x

Upgrading? See the upgrade guide.

Key Features

• MCP 2026-07-28 (stateless protocol)
• 100% MCP Conformance - server 110/110, client 440/440 on 2026-07-28
• Transports: Stdio, Streamable HTTP, and backward-compatible SSE support
• Framework Agnostic: Axum, Actix, and BYO Server integrations
• MRTR (Mid-Request Turn-Around) for server→client input requests
• Response cache (SEP-2549) with principal-scoped privacy + auto-pagination
• Per-request _meta with RequestContext
• Multi-client concurrency
• DNS Rebinding Protection
• Message Observer (Telemetry & Monitoring)
• HTTP Health Checks (for load balancers & container orchestration)
• OAuth Authentication for MCP Servers
  • Remote Oauth Provider
    • Keycloak Provider (via rust-mcp-extra)
    • WorkOS Authkit Provider (via rust-mcp-extra)
    • Scalekit Authkit Provider (via rust-mcp-extra)
• OAuth Authentication for MCP Clients (metadata discovery, CIMD, PKCE, token refresh, pluggable storage)
• Issuer-bound credentials (SEP-2352), strict iss validation (SEP-2468)

Table of Contents

• Quick Start
• Minimal MCP Server (Stdio)
• Minimal MCP Server (Streamable HTTP)
• Minimal MCP Client (Stdio)
• Usage Examples
• Macros
  • mcp_tool
  • tool_box
  • mcp_elicit
  • mcp_resource
  • mcp_resource_template
  • mcp_prompt
  • mcp_icon
• Authentication
• HTTP Server Backends (Axum & Actix)
• Cargo features
• Handler Traits
• Message Observer (Telemetry & Monitoring)
• Health Check Endpoint
• Projects using Rust MCP SDK
• Contributing
• Development
• License

Quick Start

Add to your Cargo.toml:

[dependencies]
rust-mcp-sdk = "2.0.0"  # Check crates.io for the latest version

Minimal MCP Server (Stdio)

use async_trait::async_trait;
use rust_mcp_sdk::{
    error::SdkResult, macros, mcp_icon,
    mcp_server::{server_runtime, McpServerOptions, ServerHandler},
    schema::*,
    McpServer, RequestContext, ServerDetails, StdioTransport, ToMcpServerHandler,
    TransportOptions,
};

// Define an MCP tool
#[macros::mcp_tool(name = "say_hello", description = "returns \"Hello from Rust MCP SDK!\" message")]
#[derive(Debug, ::serde::Deserialize, ::serde::Serialize, macros::JsonSchema)]
pub struct SayHelloTool {}

// Define a custom handler
#[derive(Default)]
struct HelloHandler;

#[async_trait]
impl ServerHandler for HelloHandler {
    async fn handle_list_tools_request(
        &self,
        _request: Option<PaginatedRequestParams>,
        _context: &RequestContext,
        _runtime: std::sync::Arc<dyn McpServer>,
    ) -> std::result::Result<ListToolsResult, RpcError> {
        Ok(ListToolsResult {
            tools: vec![SayHelloTool::tool()],
            meta: None,
            next_cursor: None,
            cache_scope: Default::default(),
            result_type: "complete".to_string(),
            ttl_ms: 0,
        })
    }

    async fn handle_call_tool_request(
        &self,
        params: CallToolRequestParams,
        _context: &RequestContext,
        _runtime: std::sync::Arc<dyn McpServer>,
    ) -> std::result::Result<ServerResult, CallToolError> {
        if params.name == "say_hello" {
            Ok(ServerResult::CallToolResult(CallToolResult {
                content: vec![ContentBlock::TextContent(TextContent::new(
                    "Hello from Rust MCP SDK!".to_string(),
                    None,
                    None,
                ))],
                is_error: None,
                meta: None,
                result_type: "complete".to_string(),
            }))
        } else {
            Err(CallToolError::unknown_tool(params.name))
        }
    }
}

#[tokio::main]
async fn main() -> SdkResult<()> {
    let server_details = ServerDetails {
        server_info: Implementation {
            name: "hello-rust-mcp".into(),
            version: "0.1.0".into(),
            title: Some("Hello World MCP Server".into()),
            description: Some("A minimal Rust MCP server".into()),
            icons: vec![mcp_icon!(
                src = "https://raw.githubusercontent.com/rust-mcp-stack/rust-mcp-sdk/main/assets/rust-mcp-icon.png",
                mime_type = "image/png",
                sizes = ["128x128"],
                theme = "light"
            )],
            website_url: Some("https://github.com/rust-mcp-stack/rust-mcp-sdk".into()),
        },
        capabilities: ServerCapabilities {
            tools: Some(ServerCapabilitiesTools { list_changed: None }),
            ..Default::default()
        },
        instructions: None,
        meta: None,
    };

    let transport = StdioTransport::new(TransportOptions::default())?;
    let handler = HelloHandler::default().to_mcp_server_handler();
    let server = server_runtime::create_server(McpServerOptions {
        server_details,
        transport,
        handler,
        message_observer: None,
    });
    server.start().await
}

HTTP Server Backends (Axum & Actix)

Creating a Streamable HTTP MCP server in rust-mcp-sdk allows multiple clients to connect simultaneously with no additional setup. The setup is nearly identical to the stdio example , the only difference is which HTTP backend crate you install and which function you call to create the server.

Post only - the 2026-07-28 protocol is stateless. GET and DELETE endpoints return 405 Method Not Allowed.

Axum Backend (rust-mcp-axum)

Add rust-mcp-axum to your dependencies and use create_axum_server() with AxumServerOptions.

use async_trait::async_trait;
use rust_mcp_axum::{create_axum_server, AxumServerOptions};
use rust_mcp_sdk::{
    error::SdkResult, macros,
    mcp_server::ServerHandler, schema::*,
};

// ... (define SayHelloTool and HelloHandler as shown above)

#[tokio::main]
async fn main() -> SdkResult<()> {
    let server_details = ServerDetails { /* ... */ };

    let handler = HelloHandler::default().to_mcp_server_handler();
    let server = create_axum_server(
        server_details,
        handler,
        AxumServerOptions {
            host: "127.0.0.1".to_string(),
            ..Default::default()
        },
    );
    server.start().await?;
    Ok(())
}

Actix-web Backend (rust-mcp-actix)

Add rust-mcp-actix to your dependencies and use create_actix_server() with ActixServerOptions.

use rust_mcp_actix::{create_actix_server, ActixServerOptions};
use rust_mcp_sdk::{
    error::SdkResult,
    mcp_server::ServerHandler, schema::*,
};

// ... (define SayHelloTool