mcp-protocol-sdk 0.2.4

Production-ready Rust SDK for the Model Context Protocol (MCP) with multiple transport support
Documentation

MCP Protocol SDK

Crates.io Documentation License: MIT CI Security Audit codecov Schema Compliance

A production-ready, feature-complete Rust implementation of the Model Context Protocol

The MCP Protocol SDK enables seamless integration between AI models and external systems through a standardized protocol. Build powerful tools, resources, and capabilities that AI can discover and use dynamically.

📚 Complete Documentation & Guides | 📖 API Reference | 🚀 Getting Started

✨ Features

  • 🦀 Pure Rust - Zero-cost abstractions, memory safety, and blazing performance
  • 🔌 Multiple Transports - STDIO, HTTP, WebSocket support with optional features
  • ⚡ Advanced HTTP Transport - Connection pooling, retry logic, 45% faster performance
  • 🛠️ Complete MCP Support - Tools, resources, prompts, logging, and sampling
  • 🎯 Type-Safe - Comprehensive type system with compile-time guarantees
  • 🚀 Async/Await - Built on Tokio for high-performance concurrent operations
  • 📦 Modular Design - Optional features for minimal binary size
  • 🔒 Production Ready - Comprehensive error handling, validation, and testing
  • 📊 Built-in Metrics - Performance monitoring and health checks
  • 📖 Excellent Docs - Complete guides for servers, clients, and integrations

🚀 Quick Start

Add to Your Project

[dependencies]
mcp-protocol-sdk = "0.2.3"

# Or with specific features only:
mcp-protocol-sdk = { version = "0.2.3", features = ["stdio", "validation"] }

Build an MCP Server (5 minutes)

use mcp_protocol_sdk::prelude::*;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create server
    let mut server = McpServer::new("my-calculator", "1.0.0");
    
    // Add a tool
    let calc_tool = Tool::new("add", "Add two numbers")
        .with_parameter("a", "First number", true)
        .with_parameter("b", "Second number", true);
    
    server.add_tool(calc_tool);
    
    // Handle tool calls
    server.set_tool_handler("add", |params| async move {
        let a = params["a"].as_f64().unwrap_or(0.0);
        let b = params["b"].as_f64().unwrap_or(0.0);
        Ok(json!({ "result": a + b }))
    });
    
    // Start server (compatible with Claude Desktop)
    let transport = StdioServerTransport::new();
    server.run(transport).await?;
    
    Ok(())
}

Build an MCP Client

use mcp_protocol_sdk::prelude::*;
use mcp_protocol_sdk::transport::http_advanced::{
    AdvancedHttpClientTransport, AdvancedHttpConfig
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect with advanced HTTP transport (45% faster!)
    let config = AdvancedHttpConfig::conservative(); // or ::aggressive()
    let transport = AdvancedHttpClientTransport::with_config(
        "http://localhost:3000",
        None,
        config,
    ).await?;
    
    let client = McpClient::new()
        .with_name("my-client")
        .build();
    
    client.connect(transport).await?;
    client.initialize().await?;
    
    // Use server capabilities
    let tools = client.list_tools().await?;
    let result = client.call_tool("add", json!({"a": 5, "b": 3})).await?;
    
    // Monitor performance
    let metrics = transport.get_metrics().await;
    println!("Requests/sec: {:.0}", metrics.timing.requests_per_second);
    
    Ok(())
}

🎯 Use Cases

Scenario Description Guide
🖥️ Claude Desktop Integration Add custom tools to Claude Desktop 📝 Guide
⚡ Cursor IDE Enhancement AI-powered development tools 📝 Guide
📝 VS Code Extensions Smart code assistance and automation 📝 Guide
🗄️ Database Access SQL queries and data analysis 📝 Example
🌐 API Integration External service connectivity 📝 Example
📁 File Operations Filesystem tools and utilities 📝 Example
💬 Chat Applications Real-time AI conversations 📝 Example

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   AI Client     │    │  MCP Protocol   │    │   MCP Server    │
│  (Claude, etc.) │◄──►│      SDK        │◄──►│  (Your Tools)   │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                              │
                    ┌─────────┼─────────┐
                    │         │         │
              ┌──────▼──┐ ┌────▼───┐ ┌───▼────┐
              │  STDIO  │ │  HTTP  │ │WebSocket│
              │Transport│ │Transport│ │Transport│
              └─────────┘ └────────┘ └────────┘

🔧 Feature Flags

Optimize your binary size by selecting only needed features:

Feature Description Default Size Impact
stdio STDIO transport for Claude Desktop ✅ Minimal
http HTTP transport for web integration ✅ +2MB
websocket WebSocket transport for real-time ✅ +1.5MB
validation Enhanced input validation ✅ +500KB
tracing-subscriber Built-in logging setup ❌ +300KB

Minimal Example (STDIO only):

mcp-protocol-sdk = { version = "0.2.3", default-features = false, features = ["stdio"] }

🚀 Performance

The advanced HTTP transport provides significant performance improvements:

Transport Requests/Second Average Latency Success Rate Key Features
Advanced HTTP 802 req/sec 0.02ms 100% Connection pooling, retry logic
Standard HTTP 551 req/sec 0.04ms 100% Basic HTTP client

45% Performance Improvement with advanced features! 🎯

Quick Performance Test

# Run benchmark comparison
cargo run --example transport_benchmark --all-features

# Test conservative settings (recommended)
cargo run --example conservative_http_demo --all-features

📖 Full Advanced Transport Guide

📋 Protocol Support

✅ Complete MCP 2024-11-05 Implementation

  • Core Protocol - JSON-RPC 2.0 with full error handling
  • Tools - Function calling with parameters and validation
  • Resources - Static and dynamic content access
  • Prompts - Reusable prompt templates with parameters
  • Logging - Structured logging with multiple levels
  • Sampling - LLM sampling integration and control
  • Roots - Resource root discovery and management
  • Progress - Long-running operation progress tracking

🛡️ MCP Protocol Schema Compliance

This SDK provides 100% verified compliance with the official MCP Protocol Schema (2025-03-26), ensuring seamless interoperability with all MCP-compatible systems.

✅ Comprehensive Validation

Our comprehensive test suite validates every aspect of the MCP protocol:

# Run the full schema compliance test suite
cargo test --test comprehensive_schema_tests -- --nocapture

Results: 26/26 tests passing with 100.0% compliance rate 🎉

📊 Schema Compliance Report

Component Status Features Validated
Core Types ✅ 100% Implementation, Capabilities, Content
JSON-RPC ✅ 100% Requests, Responses, Errors, Notifications, Batching
Tools ✅ 100% Definitions, Parameters, Annotations, Execution
Resources ✅ 100% Static/Dynamic, Templates, Subscriptions
Prompts ✅ 100% Templates, Arguments, Message Generation
Sampling ✅ 100% Message Creation, Model Preferences
Logging ✅ 100% All levels, Structured messages
Progress ✅ 100% Notifications, Cancellation
Roots ✅ 100% Discovery, List management
Completions ✅ 100% Auto-complete for prompts/resources

🚀 2025-03-26 Features

Full support for all latest MCP protocol enhancements:

  • 🎵 Audio Content - Native audio message support
  • 📝 Annotations - Tool safety and usage metadata
  • 🌐 Embedded Resources - Direct resource embedding
  • 📊 Enhanced Progress - Detailed progress tracking
  • 🔄 JSON-RPC Batching - Efficient bulk operations
  • 📦 Metadata Support - Rich request/response metadata

🧪 Validation Architecture

// Example: Schema validation in action
use mcp_protocol_sdk::protocol::types::*;

// All types are schema-compliant by construction
let tool = Tool::new("calculator", "Performs mathematical operations")
    .with_annotations(
        Annotations::new()
            .for_audience(vec![AnnotationAudience::User])
            .with_danger_level(DangerLevel::Low)
            .read_only()
    );

// JSON serialization matches schema exactly
assert_eq!(tool.to_json()["annotations"]["readOnly"], true);

🔍 Manual Verification

You can verify schema compliance yourself:

# 1. Run comprehensive schema tests
cargo test comprehensive_schema_validation --features validation -- --nocapture

# 2. Check specific protocol components
cargo test test_protocol_version_compliance
cargo test test_tool_with_annotations_schema_compliance
cargo test test_jsonrpc_batch_schema_compliance

# 3. Validate against official schema (if available)
# The tests verify serialization matches expected JSON-RPC format

📈 Continuous Compliance

  • Automated Testing - Every commit runs full schema validation
  • Version Tracking - Tests updated with each protocol version
  • Regression Prevention - Breaking changes detected immediately
  • Documentation Sync - Schema changes reflected in docs

🤝 Interoperability Guarantee

With 100% schema compliance, this SDK guarantees compatibility with:

  • Claude Desktop - Official Anthropic client
  • Third-party MCP Clients - Any standards-compliant implementation
  • Custom Integrations - Your own MCP-based tools
  • Future Protocol Versions - Forward compatibility design

📖 View Full Schema Compliance Details

🌍 Integration Ecosystem

AI Clients

  • Claude Desktop - Ready-to-use STDIO integration
  • Cursor IDE - Smart development assistance
  • VS Code - Extension development framework
  • Custom AI Apps - HTTP/WebSocket APIs

Development Tools

  • Jupyter Notebooks - Data science workflows
  • Streamlit Apps - Interactive AI applications
  • Browser Extensions - Web-based AI tools
  • Mobile Apps - React Native integration

📊 Examples

Example Description Transport Features
Conservative HTTP Demo Production-ready HTTP client Advanced HTTP Connection pooling, metrics
Transport Benchmark Performance comparison Multiple 45% speed improvement
Advanced HTTP Client Full-featured HTTP demo Advanced HTTP Retry logic, health checks
Echo Server Simple tool demonstration STDIO Basic tools
Database Server SQL query execution STDIO Database access
HTTP Server RESTful API integration HTTP Web services
WebSocket Server Real-time communication WebSocket Live updates
File Server File system operations STDIO File handling
Client Example Basic client usage STDIO Client patterns

🛠️ Development

Prerequisites

  • Rust 1.75+
  • Cargo

Build & Test

# Build with all features
cargo build --all-features

# Test with different feature combinations  
cargo test --no-default-features --features stdio
cargo test --all-features

# Run examples
cargo run --example echo_server --features stdio,tracing-subscriber

Feature Development

# Test minimal build
cargo check --no-default-features --lib

# Test specific transports
cargo check --no-default-features --features http
cargo check --no-default-features --features websocket

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Areas for Contribution

  • 🐛 Bug Reports - Help us improve reliability
  • 💡 Feature Requests - Suggest new capabilities
  • 📖 Documentation - Improve guides and examples
  • 🔧 Tool Integrations - Build example servers
  • 🧪 Testing - Expand test coverage
  • 🚀 Performance - Optimize critical paths

📋 Roadmap

  • Advanced Authentication - OAuth2, JWT, mTLS support
  • Monitoring Integration - Prometheus metrics, health checks
  • Plugin System - Dynamic tool loading and registration
  • Schema Registry - Tool and resource schema management
  • Load Balancing - Multiple server instance coordination
  • Caching Layer - Response caching and invalidation
  • Rate Limiting - Advanced traffic control
  • Admin Dashboard - Web-based server management

📄 License

Licensed under the MIT License.

🙏 Acknowledgments

  • Anthropic - For creating the MCP specification
  • Tokio Team - For the excellent async runtime
  • Serde Team - For JSON serialization/deserialization
  • Rust Community - For the amazing ecosystem

📚 Read the Full Documentation | 🚀 Get Started Now

Built with ❤️ in Rust