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)
- ✅ Remote Oauth Provider (for any provider with DCR support)
- ✅ 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
- 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:
[]
= "0.9.0" # Check crates.io for the latest version
Minimal MCP Server (Stdio)
use async_trait;
use ;
// Define a mcp tool
// define a custom handler
;
// implement ServerHandler
async
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;
use ;
use ;
// ... (define SayHelloTool and HelloHandler as shown above)
async
Actix-web Backend (rust-mcp-actix)
Add rust-mcp-actix to your dependencies and use create_actix_server() with ActixServerOptions.
use ;
use ;
// ... (define SayHelloTool and HelloHandler as shown above)
async
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 |
Both functions take a pre-built McpAppState and McpMountOptions, and produce routes/scopes you can merge directly into your existing router.
👉 See examples/byo-server.rs (Axum) and examples/byo-server.rs (Actix) for working examples.
Custom HTTP Framework Integrations
While we provide native Axum and Actix 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 and implementation steps.
AxumServerOptions
Axum server is highly customizable through AxumServerOptions:
let server = create_axum_server;
server.start.await?;
📝 Refer to AxumServerOptions or the rust-mcp-axum README for a complete field reference.
ActixServerOptions
ActixServerOptions mirrors AxumServerOptions field-for-field:
let server = create_actix_server;
server.start.await?;
📝 Refer to ActixServerOptions or the rust-mcp-actix README for a complete field reference.
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;
use ;
// Custom Handler to handle incoming MCP Messages
;
async
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:
)]
📝 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!;
let tools: = 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:
// Sends a request to the client asking the user to provide input
let result: ElicitResult = server.request_elicitation.await?;
// Convert result.content into a UserInfo instance
let user_info = from_elicit_result_content?;
println!;
println!;
println!;
println!;
📝 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: crateIcon = mcp_icon!;
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:
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.
AxumServerOptions
AxumServer is a lightweight Axum-based server provided by the rust-mcp-axum crate 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.
AxumServer is highly customizable through AxumServerOptions provided during initialization.
A typical example of creating an AxumServer that exposes the MCP server via Streamable HTTP and SSE transports at:
let server = create_axum_server;
server.start.await?;
📝 Refer to AxumServerOptions for a complete overview of AxumServerOptions attributes and options.
Security Considerations
When using Streamable HTTP transport, following security best practices are recommended:
- DNS rebinding protection is enabled by default. If
allowed_hostsis not set, it auto-derives fromhost:port(e.g.127.0.0.1:8080). For wildcard binds (0.0.0.0,::), explicitly configureallowed_hosts. - 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 inrust-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.macros: Provides procedural macros for simplifying the creation and manipulation of MCP Tool structures.sse: Enables support for theServer-Sent Events (SSE)transport.streamable-http: Enables support for theStreamable HTTPtransport.stdio: Enables support for thestandard input/output (stdio)transport.auth: Enables OAuth authentication support for MCP servers.tls-no-provider: Enables TLS without a crypto provider. Useful if you already use 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
[]
= "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:
[]
= { = "0.9.0", = false, = ["server","macros","stdio"] }
Optionally add rust-mcp-axum and the streamable-http feature for Streamable HTTP transport, and use rust-mcp-axum's ssl feature for TLS/SSL support.
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:
[]
= { = "0.9.0", = false, = ["client","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, anderror. 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
rust_mcp_axum::create_axum_server()for servers with Streamable HTTP/SSE transport
- Use
-
For
ServerHandlerCore:- Use
server_runtime_core::create_server()for servers with stdio transport - Use
rust_mcp_axum::create_axum_server()for servers with Streamable HTTP/SSE transport
- Use
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 withClientHandler -
Use
client_runtime_core::create_client()when working withClientHandlerCore
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 = create_server_with_options;
👉 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 AxumServerOptions:
let server = create_axum_server;
👉 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 | |
| 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.