Rust MCP SDK

A high-performance, asynchronous Rust toolkit for building MCP servers and clients.
Focus on your application logic - rust-mcp-sdk handles the protocol, transports, and the rest!
This SDK fully implements the latest MCP protocol version (2025-11-25), with backward compatibility built-in.
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.

⚠ Upgrading from v0.7.x

v0.8.0 includes breaking changes compared to v0.7. If you are upgrading, please review the breaking changes section of the release notes to update your code and dependencies accordingly.

Key Features

• ✅ Latest MCP protocol specification supported: 2025-11-25
• ✅ Transports:Stdio, Streamable HTTP, and backward-compatible SSE support
• ✅ Lightweight Axum-based server for Streamable HTTP and SSE
• ✅ 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

⚠️ 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
• HyperServerOptions
• 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
}

Minimal MCP Server (Streamable HTTP)

Creating an 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 shown above. You only need to create a Hyper server via hyper_server::create_server() and pass in the same handler and HyperServerOptions.

💡 If backward compatibility is required, you can enable SSE transport by setting sse_support to true in HyperServerOptions.

use async_trait::async_trait;
use rust_mcp_sdk::{*,error::SdkResult,event_store::InMemoryEventStore,macros,
    mcp_server::{hyper_server, HyperServerOptions, 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 handler = HelloHandler::default().to_mcp_server_handler();
    let server = hyper_server::create_server(
        server_info,
        handler,
        HyperServerOptions {
            host: "127.0.0.1".to_string(),
            event_store: Some(std::sync::Arc::new(InMemoryEventStore::default())), // enable resumability
            ..Default::default()
        },
    );
    server.start().await?;
    Ok(())
}

Minimal MCP Client (Stdio)

Following is implementation of an MCP client that starts the @modelcontextprotocol/server-everything server, displays the server's name, version, and list of tools provided by the server.

use async_trait::async_trait;
use rust_mcp_sdk::{*, error::SdkResult,
    mcp_client::{client_runtime, ClientHandler},
    schema::*,
};

// Custom Handler to handle incoming MCP Messages
pub struct MyClientHandler;
#[async_trait]
impl ClientHandler for MyClientHandler {
    // To see all the trait methods you can override,
    // check out:
    // https://github.com/rust-mcp-stack/rust-mcp-sdk/blob/main/crates/rust-mcp-sdk/src/mcp_handlers/mcp_client_handler.rs
}

#[tokio::main]
async fn main() -> SdkResult<()> {
    // Client details and capabilities
    let client_details: InitializeRequestParams = InitializeRequestParams {
        capabilities: ClientCapabilities::default(),
        client_info: Implementation {
            name: "simple-rust-mcp-client".into(),
            version: "0.1.0".into(),
            description: None,
            icons: vec![],
            title: None,
            website_url: None,
        },
        protocol_version: ProtocolVersion::V2025_11_25.into(),
        meta: None,
    };

    //  Create a transport, with options to launch @modelcontextprotocol/server-everything MCP Server
    let transport = StdioTransport::create_with_server_launch(
        "npx",vec!["-y".to_string(),"@modelcontextprotocol/server-everything@latest".to_string()],
        None,
        TransportOptions::default(),
    )?;

    // instantiate our custom handler for handling MCP messages
    let handler = MyClientHandler {};

    // Create and start the MCP client
    let client = client_runtime::create_client(client_details, transport, handler);    
    client.clone().start().await?;

    // use client methods to communicate with the MCP Server as you wish:

    let server_version = client.server_version().unwrap();    
    
    // Retrieve and display the list of tools available on the server
    let tools = client.request_tool_list(None).await?.tools;
    println!( "List of tools for {}@{}",server_version.name, server_version.version);
    tools.iter().enumerate().for_each(|(tool_index, tool)| {
        println!("  {}. {} : {}", tool_index + 1, tool.name, tool.description.clone().unwrap_or_default());
    });

    client.shut_down().await?;
    Ok(())
}

Usage Examples

👉 For more examples (stdio, Streamable HTTP, clients, auth, etc.), see the examples/ directory.

👉 If you are looking for a step-by-step tutorial on how to get started with rust-mcp-sdk , please see : Getting Started MCP Server

See hello-world-mcp-server-stdio example running in MCP Inspector :

Macros

Enable with the macros feature.

rust-mcp-sdk includes several helpful macros that simplify common tasks when building MCP servers and clients. For example, they can automatically generate tool specifications and tool schemas right from your structs, or assist with elicitation requests and responses making them completely type safe.

◾mcp_tool

Generate a Tool from a struct, with rich metadata (icons, execution hints, etc.).

example usage:

#[mcp_tool(
   name = "write_file",
   title = "Write File Tool",
   description = "Create a new file or completely overwrite an existing file with new content.",
   destructive_hint = false idempotent_hint = false open_world_hint = false read_only_hint = false,
   meta = r#"{ "key" : "value", "string_meta" : "meta value", "numeric_meta" : 15}"#,
   execution(task_support = "optional"),
   icons = [(src = "https:/website.com/write.png", mime_type = "image/png", sizes = ["128x128"], theme = "light")]
)]
#[derive(rust_mcp_macros::JsonSchema)]
pub struct WriteFileTool {
    /// The target file's path for writing content.
    pub path: String,
    /// The string content to be written to the file
    pub content: String,
}

📝 For complete documentation, example usage, and a list of all available attributes, please refer to https://crates.io/crates/rust-mcp-macros.

◾ tool_box!()

Automatically generates an enum based on the provided list of tools, making it easier to organize and manage them, especially when your application includes a large number of tools.

tool_box!(GreetingTools, [SayHelloTool, SayGoodbyeTool]);

let tools: Vec<Tool> = GreetingTools::tools();

💻 For a real-world example, check out tools/ and handle_call_tool_request(...) in rust-mcp-filesystem project

◾ mcp_elicit()

Generates type-safe elicitation (Form or URL mode) for user input.

example usage:

#[mcp_elicit(message = "Please enter your info", mode = form)]
#[derive(JsonSchema)]
pub struct UserInfo {
    #[json_schema(title = "Name", min_length = 5, max_length = 100)]
    pub name: String,
    #[json_schema(title = "Email", format = "email")]
    pub email: Option<String>,
    #[json_schema(title = "Age", minimum = 15, maximum = 125)]
    pub age: i32,
    #[json_schema(title = "Tags")]
    pub tags: Vec<String>,
}

// Sends a request to the client asking the user to provide input
let result: ElicitResult = server.request_elicitation(UserInfo::elicit_request_params()).await?;

// Convert result.content into a UserInfo instance
let user_info = UserInfo::from_elicit_result_content(result.content)?; 

println!("name: {}", user_info.name);
println!("age: {}", user_info.age);
println!("email: {}",user.email.clone().unwrap_or("not provider".into()));
println!("tags: {}", user_info.tags.join(",")); 

📝 For complete documentation, example usage, and a list of all available attributes, please refer to https://crates.io/crates/rust-mcp-macros.

◾ mcp_resource()

A procedural macro attribute that generates utility methods to create fully populated Resource instances from compile-time metadata , usually used for exposing static assets like files, images, or documents.

📝 For complete documentation, example usage, and a list of all available attributes, please refer to https://crates.io/crates/rust-mcp-macros.

◾ mcp_resource_template()

A procedural macro attribute that generates utility methods to create fully populated ResourceTemplate instances from compile-time metadata for exposing parameterized server resources.

📝 For complete documentation, example usage, and a list of all available attributes, please refer to https://crates.io/crates/rust-mcp-macros.

◾ mcp_icon!()

A convenient icon builder for implementations and tools, offering full attribute support including theme, size, mime, and more.

example usage:

let icon: crate::schema::Icon = mcp_icon!(
            src = "http://website.com/icon.png",
            mime_type = "image/png",
            sizes = ["64x64"],
            theme = "dark"
        );

Authentication

MCP server can verify tokens issued by other systems, integrate with external identity providers, or manage the entire authentication process itself. Each option offers a different balance of simplicity, security, and control.

RemoteAuthProvider

RemoteAuthProvider RemoteAuthProvider enables authentication with identity providers that support Dynamic Client Registration (DCR) such as KeyCloak and WorkOS AuthKit, letting MCP clients auto-register and obtain credentials without manual setup.

👉 See the server-oauth-remote example for how to use RemoteAuthProvider with a DCR-capable remote provider.

👉 rust-mcp-extra also offers drop-in auth providers for common identity platforms, working seamlessly with rust-mcp-sdk:

• Keycloack auth example
• WorkOS autn example

OAuthProxy

OAuthProxy enables authentication with OAuth providers that don’t support Dynamic Client Registration (DCR).It accepts any client registration request, handles the DCR on your server side and then uses your pre-registered app credentials upstream.The proxy also forwards callbacks, allowing dynamic redirect URIs to work with providers that require fixed ones.

⚠️ OAuthProxy support is still in development, please use RemoteAuthProvider for now.

HyperServerOptions

HyperServer is a lightweight Axum-based server that streamlines MCP servers by supporting Streamable HTTP and SSE transports. It supports simultaneous client connections, internal session management, and includes built-in security features like DNS rebinding protection and more.

HyperServer is highly customizable through HyperServerOptions provided during initialization.

A typical example of creating a HyperServer that exposes the MCP server via Streamable HTTP and SSE transports at:

let server = hyper_server::create_server(
    server_details,
    handler.to_mcp_server_handler(),
    HyperServerOptions {
        host: "127.0.0.1".to_string(),
        port: 8080,
        event_store: Some(std::sync::Arc::new(InMemoryEventStore::default())), // enable resumability
        auth: Some(Arc::new(auth_provider)), // enable authentication
        sse_support: false,
        ..Default::default()
    },
);

server.start().await?;

📝 Refer to HyperServerOptions for a complete overview of HyperServerOptions attributes and options.

Security Considerations

When using Streamable HTTP transport, following security best practices are recommended:

• Enable DNS rebinding protection and provide proper allowed_hosts and allowed_origins to prevent DNS rebinding attacks.
• When running locally, bind only to localhost (127.0.0.1 / localhost) rather than all network interfaces (0.0.0.0)
• Use TLS/HTTPS for production deployments

Cargo Features

The rust-mcp-sdk crate provides several features that can be enabled or disabled. By default, all features are enabled to ensure maximum functionality, but you can customize which ones to include based on your project's requirements.

Available Features

• server: Activates MCP server capabilities in rust-mcp-sdk, providing modules and APIs for building and managing MCP servers.
• client: Activates MCP client capabilities, offering modules and APIs for client development and communicating with MCP servers.
• hyper-server: This feature is necessary to enable Streamable HTTP or Server-Sent Events (SSE) transports for MCP servers. It must be used alongside the server feature to support the required server functionalities.
• ssl: This feature enables TLS/SSL support for the Streamable HTTP or Server-Sent Events (SSE) transport when used with the hyper-server.
• macros: Provides procedural macros for simplifying the creation and manipulation of MCP Tool structures.
• sse: Enables support for the Server-Sent Events (SSE) transport.
• streamable-http: Enables support for the Streamable HTTP transport.
• stdio: Enables support for the standard input/output (stdio) transport.
• tls-no-provider: Enables TLS without a crypto provider. This is useful if you are already using a different crypto provider than the aws-lc default.

Default Features

When you add rust-mcp-sdk as a dependency without specifying any features, all features are enabled by default

[dependencies]
rust-mcp-sdk = "0.9.0"

Using Only the server Features

If you only need the MCP Server functionality, you can disable the default features and explicitly enable the server feature. Add the following to your Cargo.toml:

[dependencies]
rust-mcp-sdk = { version = "0.2.0", default-features = false, features = ["server","macros","stdio"] }

Optionally add hyper-server and streamable-http for Streamable HTTP transport, and ssl feature for tls/ssl support of the hyper-server

Using Only the client Features

If you only need the MCP Client functionality, you can disable the default features and explicitly enable the client feature. Add the following to your Cargo.toml:

[dependencies]
rust-mcp-sdk = { version = "0.2.0", default-features = false, features = ["client","2024_11_05","stdio"] }

Choosing Between Standard and Core Handlers traits

Learn when to use the mcp_*_handler traits versus the lower-level mcp_*_handler_core traits for both server and client implementations. This section helps you decide based on your project's need for simplicity versus fine-grained control.

Choosing Between ServerHandler and ServerHandlerCore

rust-mcp-sdk provides two type of handler traits that you can chose from:

• ServerHandler: This is the recommended trait for your MCP project, offering a default implementation for all types of MCP messages. It includes predefined implementations within the trait, such as handling initialization or responding to ping requests, so you only need to override and customize the handler functions relevant to your specific needs. Refer to examples/common/example_server_handler.rs for an example.

• ServerHandlerCore: If you need more control over MCP messages, consider using ServerHandlerCore. It offers three primary methods to manage the three MCP message types: request, notification, and error. While still providing type-safe objects in these methods, it allows you to determine how to handle each message based on its type and parameters. Refer to examples/common/example_server_handler_core.rs for an example.

---

👉 Note: Depending on whether you choose ServerHandler or ServerHandlerCore, you must use the create_server() function from the appropriate module:

• For ServerHandler:

  • Use server_runtime::create_server() for servers with stdio transport
  • Use hyper_server::create_server() for servers with sse transport

• For ServerHandlerCore:

  • Use server_runtime_core::create_server() for servers with stdio transport
  • Use hyper_server_core::create_server() for servers with sse transport

---

Choosing Between ClientHandler and ClientHandlerCore

The same principles outlined above apply to the client-side handlers, ClientHandler and ClientHandlerCore.

• Use client_runtime::create_client() when working with ClientHandler

• Use client_runtime_core::create_client() when working with ClientHandlerCore

Both functions create an MCP client instance.

Check out the corresponding examples at: examples/simple-mcp-client-stdio.rs and examples/simple-mcp-client-stdio-core.rs.

Message Observer (Telemetry & Monitoring)

The SDK provides a McpObserver trait that serves as a non-blocking hook for intercepting all incoming and outgoing MCP messages. This is particularly useful for applying telemetry, logging, debugging, or monitoring across your server or client without modifying your core business logic.

You can implement McpObserver and attach it to your client or server during initialization:

// Create a server with a custom observer
let server = server_runtime::create_server_with_options(ServerOptions {
    initialize_result: server_details,
    transport,
    handler: handler.to_mcp_server_handler(),
    task_store: None,
    client_task_store: None,        
    // example observer that will log some info about incoming/outgoing messages
    message_observer: Some(SimpleServerObserver::new()),
});

👉 See server_observer.rs and client_observer.rs for example implementations that log messages to a remote HTTP endpoint.

These observers are utilized in the hello-world-mcp-server-stdio and simple-mcp-client-streamable-http examples. You can monitor the generated logs in real-time at https://app.beeceptor.com/console/rustmcp.

Health Check Endpoint

While not part of the official MCP spec, rust-mcp-sdk provides an optional HTTP health check endpoint. This is a practical quality-of-life feature, specifically useful when your MCP server is:

• Exposed behind load balancers or reverse proxies (e.g., NGINX, HAProxy, Cloudflare).
• Running in container orchestration environments (e.g., Kubernetes, Docker Swarm, AWS ECS).

The health check endpoint is disabled by default. You can enable it and optionally provide your own custom handler (to return specific metrics or metadata) via HyperServerOptions:

let server = hyper_server::create_server(
    server_details,
    handler.to_mcp_server_handler(),
    HyperServerOptions {
        host: "127.0.0.1".into(),
        health_endpoint: Some("/health".into()),             // enables the endpoint
        health_handler: Some(Arc::new(CustomHealth {})),     // optional: overrides default 200 OK
        ..Default::default()
    },
);

👉 See the streamable_http_healthcheck.rs example for a complete implementation demonstrating a custom JSON health handler.

Projects using Rust MCP SDK

Below is a list of projects that utilize the rust-mcp-sdk, showcasing their name, description, and links to their repositories or project pages.

	Name	Description	Link
	Rust MCP Filesystem	Fast, async MCP server enabling high-performance, modern filesystem operations with advanced features.	GitHub
	MCP Discovery	A lightweight command-line tool for discovering and documenting MCP Server capabilities.	GitHub
	mistral.rs	Blazingly fast LLM inference.	GitHub
	moon	moon is a repository management, organization, orchestration, and notification tool for the web ecosystem, written in Rust.	GitHub
	angreal	Angreal provides a way to template the structure of projects and a way of executing methods for interacting with that project in a consistent manner.	GitHub
	text-to-cypher	A high-performance Rust-based API service that translates natural language text to Cypher queries for graph databases.	GitHub
	notify-mcp	A Model Context Protocol (MCP) server that provides desktop notification functionality.	GitHub
	lst	lst is a personal lists, notes, and blog posts management application with a focus on plain-text storage, offline-first functionality, and multi-device synchronization.	GitHub
	rust-mcp-server	rust-mcp-server allows the model to perform actions on your behalf, such as building, testing, and analyzing your Rust code.	GitHub

Contributing

We welcome everyone who wishes to contribute! Please refer to the contributing guidelines for more details.

Check out our development guide for instructions on setting up, building, testing, formatting, and trying out example projects.

All contributions, including issues and pull requests, must follow Rust's Code of Conduct.

Unless explicitly stated otherwise, any contribution you submit for inclusion in rust-mcp-sdk is provided under the terms of the MIT License, without any additional conditions or restrictions.

Development

Check out our development guide for instructions on setting up, building, testing, formatting, and trying out example projects.

License

This project is licensed under the MIT License. see the LICENSE file for details.