Rust MCP SDK

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

This SDK fully implements the latest MCP protocol version (2025-11-25) and passes 100% of official MCP conformance tests.

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 for tools and user input elicitation.

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

⚠ Upgrading from v0.9.x

v0.10.0 includes breaking changes compared to v0.9.x. If you are upgrading, please review the migration guide.

Key Features

• ✅ Latest MCP protocol specification supported: 2025-11-25
• ✅ 100% MCP Conformance - passes all official client (254/254) and server (40/40) conformance tests
• ✅ Transports:Stdio, Streamable HTTP, and backward-compatible SSE support
• ✅ Framework Agnostic: Seamless Axum, Actix, and BYO Server integrations
• ✅ Multi-client concurrency
• ✅ DNS Rebinding Protection
• ✅ Resumability
• ✅ MCP Tasks support
• ✅ Batch Messages
• ✅ Streaming & non-streaming JSON response
• ✅ Message Observer (Telemetry & Monitoring)
• ✅ HTTP Health Checks (for load balancers & container orchestration)
• ✅ OAuth Authentication for MCP Servers
  • ✅ Remote Oauth Provider (for any provider with DCR support)
    • ✅ 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, DCR, PKCE, token refresh, pluggable storage)

⚠️ Project is currently under development and should be used at your own risk.

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_icon
• Authentication
  • RemoteAuthProvider
  • OAuthProxy
• HTTP Server Backends (Axum & Actix)
  • Axum Backend (rust-mcp-axum)
  • Actix-web Backend (rust-mcp-actix)
  • BYO-server: Embed MCP in your existing app
  • AxumServerOptions
  • ActixServerOptions
  • Security Considerations
• Cargo features
  • Available Features
  • Default Features
  • Using Only the server Features
  • Using Only the client Features
• Handler Traits
  • Choosing Between ServerHandler and ServerHandlerCore
  • Choosing Between ClientHandler and ClientHandlerCore
• 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 = "0.9.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_server::{server_runtime, ServerHandler},schema::*,};

// Define a 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;

// implement ServerHandler
#[async_trait]
impl ServerHandler for HelloHandler {
    // Handles requests to list available tools.
    async fn handle_list_tools_request(
        &self,
        _request: Option<PaginatedRequestParams>,
        _runtime: std::sync::Arc<dyn McpServer>,
    ) -> std::result::Result<ListToolsResult, RpcError> {
        Ok(ListToolsResult {
            tools: vec![SayHelloTool::tool()],
            meta: None,
            next_cursor: None,
        })
    }
    // Handles requests to call a specific tool.
    async fn handle_call_tool_request(&self,
        params: CallToolRequestParams,
        _runtime: std::sync::Arc<dyn McpServer>,
    ) -> std::result::Result<CallToolResult, CallToolError> {
        if params.name == "say_hello" {
            Ok(CallToolResult::text_content(vec!["Hello from Rust MCP SDK!".into()]))
        } else {
            Err(CallToolError::unknown_tool(params.name))
        }
    }
}

#[tokio::main]
async fn main() -> SdkResult<()> {
    // Define server details and capabilities
    let server_info = InitializeResult {
        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() },
        protocol_version: ProtocolVersion::V2025_11_25.into(),
        instructions: None,
        meta:None
    };

    let transport = StdioTransport::new(TransportOptions::default())?;
    let handler = HelloHandler::default().to_mcp_server_handler();
    let server = server_runtime::create_server(server_info, transport, handler);
    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.

💡 If backward compatibility with older SSE-only clients is required, both backends support enabling SSE transport by setting sse_support to true in their respective options (it defaults to true).

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,event_store::InMemoryEventStore,macros,
    mcp_server::ServerHandler,schema::*,
};

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

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

    let handler = HelloHandler::default().to_mcp_server_handler();
    let server = create_axum_server(
        server_info,
        handler,
        AxumServerOptions {
            host: "127.0.0.1".to_string(),
            event_store: Some(std::sync::Arc::new(InMemoryEventStore::default())), // enable resumability
            ..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,event_store::InMemoryEventStore,
    mcp_server::Ser