Sponsored by Deepsite.site

MCP.so

Rust MCP SDK

Created By
rust-mcp-stack8 months ago
A high-performance, asynchronous toolkit for building MCP servers and clients in Rust.
# rust
# crates-io
OverviewContentToolsComments
Content

Description

Rust MCP SDK

crates.io docs.rs build status Hello World MCP Server

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.

This project currently supports following transports:

  • stdio (Standard Input/Output)
  • sse (Server-Sent Events).

🚀 The rust-mcp-sdk includes a lightweight Axum based server that handles all core functionality seamlessly. Switching between stdio and sse is straightforward, requiring minimal code changes. The server is designed to efficiently handle multiple concurrent client connections and offers built-in support for SSL.

⚠️ Streamable HTTP transport and authentication still in progress and not yet available. Project is currently under development and should be used at your own risk.

Table of Contents

Usage Examples

MCP Server (stdio)

Create a MCP server with a tool that will print a Hello World! message:

#[tokio::main]
async fn main() -> SdkResult<()> {

    // STEP 1: Define server details and capabilities
    let server_details = InitializeResult {
        // server name and version
        server_info: Implementation {
            name: "Hello World MCP Server".to_string(),
            version: "0.1.0".to_string(),
        },
        capabilities: ServerCapabilities {
            // indicates that server support mcp tools
            tools: Some(ServerCapabilitiesTools { list_changed: None }),
            ..Default::default() // Using default values for other fields
        },
        meta: None,
        instructions: Some("server instructions...".to_string()),
        protocol_version: LATEST_PROTOCOL_VERSION.to_string(),
    };

    // STEP 2: create a std transport with default options
    let transport = StdioTransport::new(TransportOptions::default())?;

    // STEP 3: instantiate our custom handler for handling MCP messages
    let handler = MyServerHandler {};

    // STEP 4: create a MCP server
    let server: ServerRuntime = server_runtime::create_server(server_details, transport, handler);

    // STEP 5: Start the server
    server.start().await

}

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

mcp-server in rust

MCP Server (sse)

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 transform options.


// STEP 1: Define server details and capabilities
let server_details = InitializeResult {
    // server name and version
    server_info: Implementation {
        name: "Hello World MCP Server".to_string(),
        version: "0.1.0".to_string(),
    },
    capabilities: ServerCapabilities {
        // indicates that server support mcp tools
        tools: Some(ServerCapabilitiesTools { list_changed: None }),
        ..Default::default() // Using default values for other fields
    },
    meta: None,
    instructions: Some("server instructions...".to_string()),
    protocol_version: LATEST_PROTOCOL_VERSION.to_string(),
};

// 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 = hyper_server::create_server(
    server_details,
    handler,
    HyperServerOptions {
        host: "127.0.0.1".to_string(),
        ..Default::default()
    },
);

// 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)
#[mcp_tool(name = "say_hello_world", description = "Prints \"Hello World!\" message")]
#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct SayHelloTool {}

// 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.
pub struct MyServerHandler;

#[async_trait]
impl ServerHandler for MyServerHandler {
    // Handle ListToolsRequest, return list of available tools as ListToolsResult
    async fn handle_list_tools_request(&self, request: ListToolsRequest, runtime: &dyn McpServer) -> 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, request: CallToolRequest, runtime: &dyn McpServer, ) -> Result<CallToolResult, CallToolError> {

        if request.tool_name() == SayHelloTool::tool_name() {
            Ok(CallToolResult::text_content(
                "Hello World!".to_string(),
                None,
            ))
        } else {
            Err(CallToolError::unknown_tool(request.tool_name().to_string()))
        }

    }
}

👉 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-sse example running in MCP Inspector :

mcp-server in rust

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
pub struct MyClientHandler;

#[async_trait]
impl ClientHandler for MyClientHandler {
    // To check out a list of all the methods in the trait that you can override, take a look at 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<()> {

    // Step2 : Define 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(),
        },
        protocol_version: LATEST_PROTOCOL_VERSION.into(),
    };

    // Step3 : 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".to_string()],
        None, TransportOptions::default()
    )?;

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

    // STEP 5: create a MCP client
    let client = client_runtime::create_client(client_details, transport, handler);

    // STEP 6: start the MCP client
    client.clone().start().await?;


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

    // Retrieve and display the list of tools available on the server
    let server_version = client.server_version().unwrap();
    let tools = client.list_tools(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()
        );
    });

    println!("Call \"add\" tool with 100 and 28 ...");
    // Create a `Map<String, Value>` to represent the tool parameters
    let params = json!({"a": 100,"b": 28}).as_object().unwrap().clone();
    let request = CallToolRequestParams { name: "add".to_string(),arguments: Some(params)};

    // invoke the tool
    let result = client.call_tool(request).await?;

    println!("{}",result.content.first().unwrap().as_text_content()?.text);

    Ok(())
}

Here is the output :

rust-mcp-sdk-client-output

your results may vary slightly depending on the version of the MCP Server in use when you run it.

MCP Client (sse)

Creating an MCP client using the rust-mcp-sdk with the SSE transport is almost identical, 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())?;

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

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 enables the sse transport for MCP servers, supporting multiple simultaneous client connections out of the box.
  • ssl: This feature enables TLS/SSL support for the sse transport when used with the hyper-server.
  • macros: Provides procedural macros for simplifying the creation and manipulation of MCP Tool structures.

Default Features

All features are enabled by default. When you include rust-mcp-sdk as a dependency without specifying features, all will be included:

[dependencies]
rust-mcp-sdk = "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:

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

Optionally add hyper-server for sse 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"] }

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/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, 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/hello-world-mcp-server-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

  • 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 and examples/simple-mcp-client-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.

IconNameDescriptionLink
Rust MCP FilesystemFast, asynchronous MCP server for seamless filesystem operations offering enhanced capabilities, improved performance, and a robust feature set tailored for modern filesystem interactions.GitHub
MCP DiscoveryA lightweight command-line tool for discovering and documenting MCP Server capabilities.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.

Recommend Servers
TraeBuild with Free GPT-4.1 & Claude 3.7. Fully MCP-Ready.
Tavily Mcp
AiimagemultistyleA Model Context Protocol (MCP) server for image generation and manipulation using fal.ai's Stable Diffusion model.
CursorThe AI Code Editor
Howtocook Mcp基于Anduin2017 / HowToCook （程序员在家做饭指南）的mcp server，帮你推荐菜谱、规划膳食，解决“今天吃什么“的世纪难题； Based on Anduin2017/HowToCook (Programmer's Guide to Cooking at Home), MCP Server helps you recommend recipes, plan meals, and solve the century old problem of "what to eat today"
BlenderBlenderMCP connects Blender to Claude AI through the Model Context Protocol (MCP), allowing Claude to directly interact with and control Blender. This integration enables prompt assisted 3D modeling, scene creation, and manipulation.
TimeA Model Context Protocol server that provides time and timezone conversion capabilities. This server enables LLMs to get current time information and perform timezone conversions using IANA timezone names, with automatic system timezone detection.
Jina AI MCP ToolsA Model Context Protocol (MCP) server that integrates with Jina AI Search Foundation APIs.
Playwright McpPlaywright MCP server
Baidu Map百度地图核心API现已全面兼容MCP协议，是国内首家兼容MCP协议的地图服务商。
MiniMax MCPOfficial MiniMax Model Context Protocol (MCP) server that enables interaction with powerful Text to Speech, image generation and video generation APIs.
Serper MCP ServerA Serper MCP Server
Visual Studio Code - Open Source ("Code - OSS")Visual Studio Code
Zhipu Web SearchZhipu Web Search MCP Server is a search engine specifically designed for large models. It integrates four search engines, allowing users to flexibly compare and switch between them. Building upon the web crawling and ranking capabilities of traditional search engines, it enhances intent recognition capabilities, returning results more suitable for large model processing (such as webpage titles, URLs, summaries, site names, site icons, etc.). This helps AI applications achieve "dynamic knowledge acquisition" and "precise scenario adaptation" capabilities.
Amap Maps高德地图官方 MCP Server
DeepChatYour AI Partner on Desktop
ChatWiseThe second fastest AI chatbot™
MCP AdvisorMCP Advisor & Installation - Use the right MCP server for your needs
EdgeOne Pages MCPAn MCP service designed for deploying HTML content to EdgeOne Pages and obtaining an accessible public URL.
WindsurfThe new purpose-built IDE to harness magic
Context7Context7 MCP Server -- Up-to-date code documentation for LLMs and AI code editors