Rust MCP SDK
A high-performance, asynchronous toolkit for building MCP servers and clients. Focus on your app's logic while rust-mcp-sdk takes care of the rest!
rust-mcp-sdk provides the necessary components for developing both servers and clients in the MCP ecosystem. Leveraging the rust-mcp-schema crate simplifies the process of building robust and reliable MCP servers and clients, ensuring consistency and minimizing errors in data handling and message processing.
rust-mcp-sdk supports all three official versions of the MCP protocol. By default, it uses the 2025-06-18 version, but earlier versions can be enabled via Cargo features.
This project supports following transports:
- Stdio (Standard Input/Output)
- Streamable HTTP
- SSE (Server-Sent Events)
🚀 The rust-mcp-sdk includes a lightweight Axum based server that handles all core functionality seamlessly. Switching between stdio
and Streamable HTTP
is straightforward, requiring minimal code changes. The server is designed to efficiently handle multiple concurrent client connections and offers built-in support for SSL.
MCP Streamable HTTP Support
- ✅ Streamable HTTP Support for MCP Servers
- ✅ DNS Rebinding Protection
- ✅ Batch Messages
- ✅ Streaming & non-streaming JSON response
- ✅ Streamable HTTP Support for MCP Clients
- ✅ Resumability
- ⬜ Oauth Authentication
⚠️ Project is currently under development and should be used at your own risk.
Table of Contents
- Usage Examples
- Macros
- Getting Started
- HyperServerOptions
- Cargo features
- Choosing Between Standard and Core Handlers traits
- Projects using Rust MCP SDK
- Contributing
- Development
- License
Usage Examples
MCP Server (stdio)
Create a MCP server with a tool
that will print a Hello World!
message:
async
See hello-world-mcp-server-stdio example running in MCP Inspector :
MCP Server (Streamable HTTP)
Creating an MCP server in rust-mcp-sdk
with the sse
transport allows multiple clients to connect simultaneously with no additional setup.
Simply create a Hyper Server using hyper_server::create_server()
and pass in the same handler and HyperServerOptions.
💡 By default, both Streamable HTTP and SSE transports are enabled for backward compatibility. To disable the SSE transport , set the sse_support
to false in the HyperServerOptions
.
// STEP 1: Define server details and capabilities
let server_details = InitializeResult ;
// STEP 2: instantiate our custom handler for handling MCP messages
let handler = MyServerHandler ;
// STEP 3: instantiate HyperServer, providing `server_details` , `handler` and HyperServerOptions
let server = create_server;
// STEP 4: Start the server
server.start.await?;
Ok
The implementation of MyServerHandler
is the same regardless of the transport used and could be as simple as the following:
// STEP 1: Define a rust_mcp_schema::Tool ( we need one with no parameters for this example)
// STEP 2: Implement ServerHandler trait for a custom handler
// For this example , we only need handle_list_tools_request() and handle_call_tool_request() methods.
;
👉 For a more detailed example of a Hello World MCP Server that supports multiple tools and provides more type-safe handling of CallToolRequest
, check out: examples/hello-world-mcp-server
See hello-world-server-streamable-http example running in MCP Inspector :
MCP Client (stdio)
Create an MCP client that starts the @modelcontextprotocol/server-everything server, displays the server's name, version, and list of tools, then uses the add tool provided by the server to sum 120 and 28, printing the result.
// STEP 1: Custom Handler to handle incoming MCP Messages
;
async
Here is the output :
your results may vary slightly depending on the version of the MCP Server in use when you run it.
MCP Client (Streamable HTTP)
// STEP 1: Custom Handler to handle incoming MCP Messages
;
async
👉 see examples/simple-mcp-client-streamable-http for a complete working example.
MCP Client (sse)
Creating an MCP client using the rust-mcp-sdk
with the SSE transport is almost identical to the stdio example , with one exception at step 3
. Instead of creating a StdioTransport
, you simply create a ClientSseTransport
. The rest of the code remains the same:
- let transport = StdioTransport::create_with_server_launch(
- "npx",
- vec![ "-y".to_string(), "@modelcontextprotocol/server-everything".to_string()],
- None, TransportOptions::default()
-)?;
+ let transport = ClientSseTransport::new(MCP_SERVER_URL, ClientSseTransportOptions::default())?;
👉 see examples/simple-mcp-client-sse for a complete working example.
Macros
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.
To use these macros, ensure the
macros
feature is enabled in your Cargo.toml.
mcp_tool
mcp_tool
is a procedural macro attribute that helps generating rust_mcp_schema::Tool from a struct.
Usage example:
// Now we can call `tool()` method on it to get a Tool instance
let Tool = tool;
💻 For a real-world example, check out any of the tools available at: https://github.com/rust-mcp-stack/rust-mcp-filesystem/tree/main/src/tools
tool_box
tool_box
generates an enum from a provided list of tools, making it easier to organize and manage them, especially when your application includes a large number of tools.
It accepts an array of tools and generates an enum where each tool becomes a variant of the enum.
Generated enum has a tools()
function that returns a Vec<Tool>
, and a TryFrom<CallToolRequestParams>
trait implementation that could be used to convert a ToolRequest into a Tool instance.
Usage example:
// Accepts an array of tools and generates an enum named `FileSystemTools`,
// where each tool becomes a variant of the enum.
tool_box!;
// now in the app, we can use the FileSystemTools, like:
let all_tools: = tools;
💻 To see a real-world example of that please see :
tool_box
macro usage: https://github.com/rust-mcp-stack/rust-mcp-filesystem/blob/main/src/tools.rs- using
tools()
in list tools request : https://github.com/rust-mcp-stack/rust-mcp-filesystem/blob/main/src/handler.rs - using
try_from
in call tool_request: https://github.com/rust-mcp-stack/rust-mcp-filesystem/blob/main/src/handler.rs
mcp_elicit
The mcp_elicit
macro generates implementations for the annotated struct to facilitate data elicitation. It enables struct to generate ElicitRequestedSchema
and also parsing a map of field names to ElicitResultContentValue
values back into the struct, supporting both required and optional fields. The generated implementation includes:
- A
message()
method returning the elicitation message as a string. - A
requested_schema()
method returning anElicitRequestedSchema
based on the struct’s JSON schema. - A
from_content_map()
method to convert a map ofElicitResultContentValue
values into a struct instance.
Attributes
message
- An optional string (orconcat!(...)
expression) to prompt the user or system for input. Defaults to an empty string if not provided.
Usage example:
// A struct that could be used to send elicit request and get the input from the user
// send a Elicit Request , ask for UserInfo data and convert the result back to a valid UserInfo instance
let result: ElicitResult = server
.elicit_input
.await?;
// Create a UserInfo instance using data provided by the user on the client side
let user_info = from_content_map?;
💻 For mre info please see :
Getting Started
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
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 = create_server;
server.start.await?;
Here is a list of available options with descriptions for configuring the HyperServer:
Security Considerations
When using Streamable HTTP transport, following security best practices are recommended:
- Enable DNS rebinding protection and provide proper
allowed_hosts
andallowed_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 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. -
hyper-server
: This feature is necessary to enableStreamable HTTP
orServer-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 theStreamable HTTP
orServer-Sent Events (SSE)
transport when used with thehyper-server
. -
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 HTTP
transport. -
stdio
: Enables support for thestandard 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.
MCP Protocol Versions with Corresponding Features
2025_06_18
: Activates MCP Protocol version 2025-06-18 (enabled by default)2025_03_26
: Activates MCP Protocol version 2025-03-262024_11_05
: Activates MCP Protocol version 2024-11-05
Note: MCP protocol versions are mutually exclusive—only one can be active at any given time.
Default Features
When you add rust-mcp-sdk as a dependency without specifying any features, all features are included, with the latest MCP Protocol version enabled by default:
[]
= "0.2.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.2.0", = false, = ["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:
[]
= { = "0.2.0", = false, = ["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/hello-world-mcp-server-stdio/src/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/hello-world-mcp-server-stdio-core/src/handler.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
- Use
-
For
ServerHandlerCore
:- Use
server_runtime_core::create_server()
for servers with stdio transport - Use
hyper_server_core::create_server()
for servers with 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 and examples/simple-mcp-client-stdio-core.
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.