Rust MCP SDK

---

**🥇 Tier 1 SDK：**通过了 100% 的计分一致性场景，且官方 MCP 一致性工具的 tier-check 根据 SEP-1730 报告为 Tier 1。Tier-check 运行记录 · 发布报告

✅ 此 SDK 完整实现了 MCP 2026-07-28 无状态协议，并通过了 100% 的官方 MCP 一致性测试。

rust-mcp-sdk 提供了在 MCP 生态系统中开发服务端和客户端所需的组件。它使用 rust-mcp-schema crate 提供类型安全的架构对象，并包含强大的过程宏。

专注于应用逻辑，rust-mcp-sdk 将负责协议、传输及其他所有事项。

---

**版本说明：**这是 rust-mcp-sdk 2.x，实现了新的 MCP 2026-07-28（无状态）规范。 对于之前的 MCP 2025-11-25 规范，请使用 rust-mcp-sdk 1.x。 请参阅升级指南，了解如何从 1.x 迁移到 2.0。

版本矩阵：

SDK 版本	协议	分支
2.0	MCP 2026-07-28（无状态）	main
1.x (LTS)	MCP 2025-11-25	release-1.x

**准备升级？**请参阅升级指南。

---

主要功能

• ✅ 支持最新 MCP 协议规范：2026-07-28
• 🥇 Tier 1 SDK - 官方 MCP 一致性工具的 tier-check 根据 SEP-1730 报告为 Tier 1。查看 tier-check 运行记录·
• ✅ 100% MCP 一致性 - 通过所有官方客户端（254/254）和服务端（40/40）一致性测试
• ✅ 传输方式：Stdio、Streamable HTTP，以及向后兼容的 SSE 支持
• ✅ 框架无关：支持 Axum、Actix 和自选服务端集成
• ✅ 为服务端→客户端输入请求提供 MRTR（请求中往返）
• ✅ 响应缓存（SEP-2549），支持按主体隔离隐私 + 自动分页
• ✅ 使用 RequestContext 提供逐请求 _meta
• ✅ 多客户端并发
• ✅ DNS 重绑定防护
• ✅ 消息观察器（遥测与监控）
• ✅ HTTP 健康检查（用于负载均衡器和容器编排）
• ✅ MCP 服务的 OAuth 身份验证
  • ✅ 远程 OAuth 提供方
    • Keycloak 提供方（通过 rust-mcp-extra）
    • WorkOS Authkit 提供方（通过 rust-mcp-extra）
    • Scalekit Authkit 提供方（通过 rust-mcp-extra）
• ✅ MCP 客户端的 OAuth 身份验证（元数据发现、CIMD、PKCE、令牌刷新、可插拔存储）
• ✅ 与发行方绑定的凭据（SEP-2352），严格验证 iss（SEP-2468）

目录

• 快速开始
• 最简 MCP 服务（Stdio）
• 最简 MCP 服务（Streamable HTTP）
• 最简 MCP 客户端（Stdio）
• 使用示例
• 宏
  • mcp_tool
  • tool_box
  • mcp_elicit
  • mcp_resource
  • mcp_resource_template
  • mcp_prompt
  • mcp_icon
• 身份验证
• HTTP 服务端后端（Axum 和 Actix）
• Cargo 功能
• 处理器 Trait
• 消息观察器（遥测与监控）
• 健康检查端点
• 贡献
• 开发
• 许可证

快速开始

添加到你的 Cargo.toml：

[dependencies]
rust-mcp-sdk = "2.0.0"  # Check crates.io for the latest version

最简 MCP 服务（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 服务端后端（Axum 和 Actix）

在 rust-mcp-sdk 中创建 Streamable HTTP MCP 服务后，多个客户端即可同时连接，无需额外设置。配置几乎与 stdio 示例相同，唯一的区别是安装哪个 HTTP 后端 crate，以及调用哪个函数来创建服务。

仅支持 POST——2026-07-28 协议是无状态的。GET 和 DELETE 端点会返回 405 Method Not Allowed。

Axum 后端（rust-mcp-axum）

将 rust-mcp-axum 添加到依赖项，并使用 AxumServerOptions 调用 create_axum_server()。

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 后端（rust-mcp-actix）

将 rust-mcp-actix 添加到依赖项，并使用 ActixServerOptions 调用 create_actix_server()。

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(())
}

自带服务端：在现有应用中嵌入 MCP

两个后端都支持 自带服务端（BYO-server，Bring Your Own Server）模式，可将 MCP 端点挂载到你已有的路由器或应用中，无需移交服务端的生命周期管理。

后端	函数	文档
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

自定义 HTTP 框架集成

该 SDK 完全独立于框架。如果你使用其他 HTTP 框架（如 Rocket、Salvo 或 Warp），可以通过将框架原生的 Request/Response 类型适配到 SDK 的核心 HTTP 处理逻辑，构建自定义集成。

架构详情请参阅自定义 HTTP 框架集成指南。

AxumServerOptions

Axum 服务端可通过 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?;

安全注意事项

• 默认启用 DNS 重绑定防护。如果未设置 allowed_hosts，系统会根据 host:port 自动推导。
• 在本地运行时，仅绑定到 localhost（127.0.0.1 / localhost），不要绑定到所有网络接口（0.0.0.0）。
• 在生产环境部署时使用 TLS/HTTPS。

以下是 MCP 客户端的实现示例：它会启动 @modelcontextprotocol/server-everything 服务端，发现服务端的功能，列出可用工具，并调用一个工具。

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(())
}

用法示例

更多示例（stdio、Streamable HTTP、客户端、身份验证等），请参阅 examples/ 目录。

👉 分步教程（服务端、客户端、HTTP 部署、OAuth 等）请参阅文档网站。

查看在 MCP Inspector 中运行的 hello-world-mcp-server-stdio 示例：

宏

通过 macros 功能启用。

mcp_tool

根据结构体生成一个 Tool，并附带元数据（图标、提示等）。

#[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!()

根据提供的工具列表自动生成枚举。

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

mcp_elicit()

为用户输入生成类型安全的引导收集功能（Form 或 URL 模式）。

#[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()

过程宏属性，可根据编译时元数据生成实用方法，用于创建内容完整的 Resource 实例，通常用于公开文件、图像或文档等静态资源。它还会生成一个可用于 match 模式的 RESOURCE_URI 关联常量，以及一个 resource_mime_type() 访问器。

📝 完整文档、使用示例以及所有可用属性的列表，请参阅 https://crates.io/crates/rust-mcp-macros。

◾ mcp_resource_template()

过程宏属性，可根据编译时元数据生成实用方法，用于创建内容完整的 ResourceTemplate 实例，以公开参数化的服务资源。它还会生成一个可用于 match 模式的 RESOURCE_URI_TEMPLATE 关联常量，以及一个 resource_template_mime_type() 访问器。

📝 完整文档、使用示例以及所有可用属性的列表，请参阅 https://crates.io/crates/rust-mcp-macros。

◾ mcp_prompt()

过程宏属性，可根据编译时元数据生成实用方法，用于创建内容完整的 Prompt 实例；此外，如果提供可选的 messages 属性，还可解析请求参数（from_arguments），并将其渲染为 GetPromptResult（render）。结构体字段会成为有类型的提示词参数（String = 必填，Option<String> = 可选，String + default = 备用值）；提示词的获取处理程序本身由用户实现。

📝 完整文档、使用示例以及所有可用属性的列表，请参阅 https://crates.io/crates/rust-mcp-macros。

◾ mcp_icon!()

便捷的图标构建器，适用于实现和工具，支持包括主题、尺寸、mime 等在内的完整属性。

使用示例：

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

身份验证

MCP 服务可以验证由其他系统签发的令牌、集成外部身份提供商，或管理整个身份验证流程。

RemoteAuthProvider

RemoteAuthProvider 支持通过支持动态客户端注册（DCR）的身份提供商进行身份验证，让 MCP 客户端自动注册并获取凭据。

OAuthProxy

OAuthProxy 支持通过不支持 DCR 的 OAuth 提供商进行身份验证。

Cargo 功能

可用功能

• server：启用 MCP 服务功能
• client：启用 MCP 客户端功能
• macros：用于 Tool、Elicit、Resource 结构的过程宏
• sse：Server-Sent Events（SSE）传输
• streamable-http：Streamable HTTP 传输
• stdio：标准输入/输出（stdio）传输
• auth：为 MCP 服务提供 OAuth 身份验证支持
• tls-no-provider：不使用加密提供程序的 TLS

默认功能

默认情况下会启用所有功能：

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

仅使用服务端功能

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

仅使用客户端功能

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

处理程序 Trait

在 ServerHandler 和 ServerHandlerCore 之间进行选择

• ServerHandler：推荐使用。为所有 MCP 消息提供默认实现。只需重写所需部分。
• ServerHandlerCore：完全控制请求、通知和错误的分发。

注意： 根据实现的处理程序，使用 server_runtime::create_server() 或 server_runtime_core::create_server()。

在 ClientHandler 和 ClientHandlerCore 之间进行选择

客户端侧也遵循相同原则：使用 client_runtime::create_client() 和 ClientHandler，或使用 client_runtime_core::create_client() 和 ClientHandlerCore。

消息观察器（遥测与监控）

实现 McpObserver，以拦截所有传入和传出的 MCP 消息，用于遥测、日志记录、调试或监控。

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

健康检查端点

可选的 HTTP 健康检查端点，供负载均衡器和容器编排使用：

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()
    },
);

贡献

欢迎所有希望参与贡献的人！更多详情请参阅贡献指南。

请查看我们的开发指南，了解如何设置、构建、测试、格式化项目以及试用示例项目。

所有贡献（包括问题和拉取请求）都必须遵循 Rust 行为准则。

除非另有明确说明，否则你提交以纳入 rust-mcp-sdk 的任何贡献均依据 MIT 许可证条款提供，不附加任何条件或限制。

开发

请查看我们的开发指南，了解如何设置、构建、测试、格式化项目以及试用示例项目。

许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。