GitHub - rust-mcp-stack/rust-mcp-sdk: A high-performance, asynchronous toolkit for building MCP servers and clients in Rust.

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) - no initialize, no sessions
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)

Quick Start
Minimal MCP Server (Stdio)
Minimal MCP Server (Streamable HTTP)
Minimal MCP Client (Stdio)
Usage Examples
Macros
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 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_actix_server(
        server_details,
        handler,
        ActixServerOptions {
            host: "127.0.0.1".to_string(),
            ..Default::default()
        },
    );
    server.start().await?;
    Ok(())
}

BYO-server: Embed MCP in your Existing App

Both backends support a BYO-server (Bring Your Own Server) mode, letting you mount MCP endpoints onto a router or app you already control - no need to hand over the server lifecycle.

Backend	Function	Docs
Axum	`mcp_routes(state, &mount_opts, http_handler)`	`rust-mcp-axum` README
Actix-web	`mcp_scope(state, http_handler, &mount_opts)`	`rust-mcp-actix` README

Custom HTTP Framework Integrations

The SDK is completely framework-agnostic. If you are using a different HTTP framework (like Rocket, Salvo, or Warp), you can build a custom integration by adapting your framework's native Request/Response types to the SDK's core HTTP handling logic.

See the Custom HTTP Framework Integration Guide for architectural details.

AxumServerOptions

Axum server is highly customizable through AxumServerOptions:

let server = create_axum_server(
    server_details,
    handler.to_mcp_server_handler(),
    AxumServerOptions {
        host: "127.0.0.1".to_string(),
        port: 8080,
        auth: Some(Arc::new(auth_provider)),           // enable authentication
        health_endpoint: Some("/health".into()),         // health check
        sse_support: true,                               // backward-compat SSE
        ..Default::default()
    },
);
server.start().await?;

Security Considerations

DNS rebinding protection is enabled by default. If allowed_hosts is not set, it auto-derives from host:port.
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

Following is implementation of an MCP client that starts the @modelcontextprotocol/server-everything server, discovers the server's capabilities, lists available tools, and calls a tool.

use async_trait::async_trait;
use rust_mcp_sdk::{
    error::SdkResult,
    mcp_client::{client_runtime, ClientHandler, McpClientOptions},
    schema::*,
    ClientDetails, McpClient, StdioTransport, ToMcpClientHandler, TransportOptions,
};

pub struct MyClientHandler;
#[async_trait]
impl ClientHandler for MyClientHandler {
    // Override handler methods as needed.
    // See: crates/rust-mcp-sdk/src/mcp_handlers/mcp_client_handler.rs
}

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

    let transport = StdioTransport::create_with_server_launch(
        "npx",
        vec!["-y".to_string(), "@modelcontextprotocol/server-everything@latest".to_string()],
        None,
        TransportOptions::default(),
    )?;

    let handler = MyClientHandler {};
    let client = client_runtime::create_client(McpClientOptions::new(
        client_details,
        transport,
        handler.to_mcp_client_handler(),
    ));
    client.clone().start().await?;

    // Discover the server
    let discover = client.request_discover(Default::default()).await?;
    println!("Supported protocol versions: {:?}", discover.supported_versions);

    // List tools
    let tools = client.request_tool_list(None).await?.tools;
    tools.iter().enumerate().for_each(|(i, tool)| {
        println!("  {}. {} : {}", i + 1, tool.name, tool.description.unwrap_or_default());
    });

    // Call a tool (supports MRTR auto-retry)
    let result = client.call_tool(CallToolRequestParams {
        name: "say_hello".to_string(),
        arguments: None,
        input_responses: None,
        request_state: None,
        meta: RequestMetaObject::default(),
    }).await?;

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

Usage Examples

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

👉 For step-by-step tutorials (server, client, HTTP deployment, OAuth, and more), see the documentation site.

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

Macros

Enable with the macros feature.

`mcp_tool`

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

#[mcp_tool(
    name = "write_file",
    title = "Write File Tool",
    description = "Create or overwrite a file with new content.",
    destructive_hint = false, idempotent_hint = false, open_world_hint = false, read_only_hint = false,
    meta = r#"{ "key": "value" }"#,
    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,
}

`tool_box!()`

Automatically generates an enum based on the provided list of tools.

tool_box!(GreetingTools, [SayHelloTool, SayGoodbyeTool]);
let tools: Vec<Tool> = GreetingTools::tools();

`mcp_elicit()`

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

#[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>,
}

◾ 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. Also generates a RESOURCE_URI associated constant, usable in match patterns, and a resource_mime_type() accessor.

📝 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. Also generates a RESOURCE_URI_TEMPLATE associated constant, usable in match patterns, and a resource_template_mime_type() accessor.

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

◾ mcp_prompt()

A procedural macro attribute that generates utility methods to create fully populated Prompt instances from compile-time metadata, and , when the optional messages attribute is provided , to parse request arguments (from_arguments) and render them into a GetPromptResult (render). Struct fields become typed prompt arguments (String = required, Option<String> = optional, String + default = fallback), the prompts/get handler itself is left to the user.

📝 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 servers can verify tokens issued by other systems, integrate with external identity providers, or manage the entire authentication process.

RemoteAuthProvider

RemoteAuthProvider enables authentication with identity providers that support Dynamic Client Registration (DCR), letting MCP clients auto-register and obtain credentials.

OAuthProxy

OAuthProxy enables authentication with OAuth providers that don't support DCR.

Cargo Features

Available Features

server: Activates MCP server capabilities
client: Activates MCP client capabilities
macros: Procedural macros for Tool, Elicit, Resource structures
sse: Server-Sent Events (SSE) transport
streamable-http: Streamable HTTP transport
stdio: Standard input/output (stdio) transport
auth: OAuth authentication support for MCP servers
tls-no-provider: TLS without a crypto provider

Default Features

All features are enabled by default:

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

Using Only the Server Features

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

Using Only the Client Features

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

Handler Traits

Choosing Between `ServerHandler` and `ServerHandlerCore`

ServerHandler: Recommended. Default implementations for all MCP messages. Override only what you need.
ServerHandlerCore: Full control over request/notification/error dispatch.

Note: Use server_runtime::create_server() or server_runtime_core::create_server() depending on which handler you implement.

Choosing Between `ClientHandler` and `ClientHandlerCore`

Same principles apply on the client side: use client_runtime::create_client() with ClientHandler, or client_runtime_core::create_client() with ClientHandlerCore.

Message Observer (Telemetry & Monitoring)

Implement McpObserver to intercept all incoming and outgoing MCP messages for telemetry, logging, debugging, or monitoring.

let server = server_runtime::create_server(McpServerOptions {
    server_details,
    transport,
    handler: handler.to_mcp_server_handler(),
    message_observer: Some(SimpleServerObserver::new()),
});

Health Check Endpoint

An optional HTTP health check endpoint for load balancers and container orchestration:

let server = create_axum_server(
    server_details,
    handler.to_mcp_server_handler(),
    AxumServerOptions {
        host: "127.0.0.1".into(),
        health_endpoint: Some("/health".into()),
        ..Default::default()
    },
);

Projects using Rust MCP SDK

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
destructive_command_guard	The Destructive Command Guard (dcg) is for blocking dangerous git and shell commands from being executed by agents. - Dicklesworthstone/destructive_command_guard	GitHub
enumrust	Subdomain Enumerator and Simple Crawler. Contribute to KingOfBugbounty/enumrust development by creating an account on GitHub.	GitHub
tracey	CLI, Web, LSP, and MCP toolkit to measure spec coverage in Rust codebases - bearcove/tracey	GitHub
Glass	Glass - a fast and free IDA Pro alternative. Contribute to azw413/Glass development by creating an account on GitHub.	GitHub
ghost	Simple background process manager for Unix systems - skanehira/ghost	GitHub
aprender	Next Generation Machine Learning, Statistics and Deep Learning in PURE Rust - paiml/aprender	GitHub
mcp-cpp	MCP server tailored to work with large C/C++ codebases - mpsm/mcp-cpp	GitHub
agent-diva	Next Generation AI Agent(AKA:nanobot-rs-pro). Contribute to ProjectViVy/agent-diva development by creating an account on GitHub.	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
ruskel	Ruskel generates skeletonized outlines of Rust crates. - cortesi/ruskel	GitHub
ai-agent	Idiomatic agent sdk inspired by the claude code source leak. - snailwei/ai-agent	GitHub
mycelium	Mycelium API Gateway, the ultimate solution for secure, flexible, and multi-tenant API management - LepistaBioinformatics/mycelium	GitHub
text-to-cypher	A high-performance Rust-based API service that translates natural language text to Cypher queries for graph databases.	GitHub
lunex	All-in-One Workspace AI. Contribute to zen8labs/lunex development by creating an account on GitHub.	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

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.

Name		Name	Last commit message	Last commit date
.cargo		.cargo
.github		.github
assets		assets
crates		crates
doc		doc
docs-site		docs-site
docs		docs
.gitignore		.gitignore
.release-config.json		.release-config.json
.release-manifest.json		.release-manifest.json
BREAKING_CHANGES.md		BREAKING_CHANGES.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
DEPENDENCY_POLICY.md		DEPENDENCY_POLICY.md
LICENSE		LICENSE
Makefile.toml		Makefile.toml
README.md		README.md
ROADMAP.md		ROADMAP.md
SECURITY.md		SECURITY.md
UPGRADING.md		UPGRADING.md
VERSIONING.md		VERSIONING.md
_typos.toml		_typos.toml
development.md		development.md
renovate.json		renovate.json

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

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

Table of Contents

Quick Start

Minimal MCP Server (Stdio)

HTTP Server Backends (Axum & Actix)

Axum Backend (rust-mcp-axum)

Actix-web Backend (rust-mcp-actix)

BYO-server: Embed MCP in your Existing App

Custom HTTP Framework Integrations

AxumServerOptions

Security Considerations

Usage Examples

Macros

mcp_tool

tool_box!()

mcp_elicit()

◾ mcp_resource()

◾ mcp_resource_template()

◾ mcp_prompt()

◾ mcp_icon!()

Authentication

RemoteAuthProvider

OAuthProxy

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

About

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Used by

Contributors

Languages

Axum Backend (`rust-mcp-axum`)

Actix-web Backend (`rust-mcp-actix`)

`mcp_tool`

`tool_box!()`

`mcp_elicit()`

◾ `mcp_icon!()`

Choosing Between `ServerHandler` and `ServerHandlerCore`

Choosing Between `ClientHandler` and `ClientHandlerCore`