MCP Protocol SDK

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

🚀 Quick Start: Getting Started | Implementation Guide | Examples

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.

🚀 v0.5.0 Released - Production-ready SDK with comprehensive GitHub Actions CI/CD, enhanced documentation, and complete development infrastructure.

📚 Documentation | 📖 API Reference | 🚀 Getting Started | 🆚 vs Official SDK

🎯 Quick Links: 📖 Implementation Guide | 🌍 Platform Support | 🔧 Examples | 🚀 Transports

✨ Features

• 🦀 Pure Rust - Zero-cost abstractions, memory safety, and blazing performance
• 🌍 Multi-Platform - Native support for Linux, macOS, Windows + ARM64/Intel architectures
• 🔌 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
• 📦 Unified Architecture - All functionality in one crate
• 🔒 Production Ready - 97 comprehensive tests, full validation, and error handling
• 🆕 Latest Schema - 100% compliant with MCP 2025-06-18 specification
• 📊 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.5.0"
tokio = { version = "1.0", features = ["full"] }
async-trait = "0.1"
serde_json = "1.0"

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

Build an MCP Server (Working Example)

use mcp_protocol_sdk::prelude::*;
use async_trait::async_trait;
use std::collections::HashMap;
use serde_json::{Value, json};

// Step 1: Create a tool handler (required by actual API)
struct CalculatorHandler;

#[async_trait]
impl ToolHandler for CalculatorHandler {
    async fn call(&self, arguments: HashMap<String, Value>) -> McpResult<ToolResult> {
        let a = arguments
            .get("a")
            .and_then(|v| v.as_f64())
            .ok_or_else(|| McpError::Validation("Missing 'a' parameter".to_string()))?;
        
        let b = arguments
            .get("b")
            .and_then(|v| v.as_f64())
            .ok_or_else(|| McpError::Validation("Missing 'b' parameter".to_string()))?;
        
        let result = a + b;
        
        Ok(ToolResult {
            content: vec![Content::text(result.to_string())],
            is_error: None,
            structured_content: Some(json!({
                "operation": "addition",
                "operands": [a, b],
                "result": result
            })),
            meta: None,
        })
    }
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create server (note: requires String parameters)
    let mut server = McpServer::new("my-calculator".to_string(), "1.0.0".to_string());
    
    // Add a tool (actual working API)
    server.add_tool(
        "add".to_string(),
        Some("Add two numbers".to_string()),
        json!({
            "type": "object",
            "properties": {
                "a": {
                    "type": "number",
                    "description": "First number"
                },
                "b": {
                    "type": "number", 
                    "description": "Second number"
                }
            },
            "required": ["a", "b"]
        }),
        CalculatorHandler,
    ).await?;
    
    // Start server (compatible with Claude Desktop)
    use mcp_protocol_sdk::transport::stdio::StdioServerTransport;
    let transport = StdioServerTransport::new();
    server.start(transport).await?;
    
    Ok(())
}

Build an MCP Client

use mcp_protocol_sdk::prelude::*;
use mcp_protocol_sdk::client::McpClient;
use mcp_protocol_sdk::transport::traits::TransportConfig;

#[cfg(feature = "http")]
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    use mcp_protocol_sdk::transport::http::HttpClientTransport;
    
    // Connect with advanced HTTP transport (45% faster!)
    let config = TransportConfig {
        connect_timeout_ms: Some(5_000),
        read_timeout_ms: Some(30_000),
        write_timeout_ms: Some(30_000),
        max_message_size: Some(1024 * 1024), // 1MB
        keep_alive_ms: Some(60_000),         // 1 minute
        compression: true,
        headers: std::collections::HashMap::new(),
    };
    
    let transport = HttpClientTransport::with_config(
        "http://localhost:3000",
        None,
        config,
    ).await?;
    
    let mut client = McpClient::new("my-client".to_string(), "1.0.0".to_string());
    
    // connect() returns InitializeResult and calls initialize() internally
    let init_result = client.connect(transport).await?;
    
    println!("Connected to: {} v{}", 
        init_result.server_info.name,
        init_result.server_info.version
    );
    
    // Note: Use server capabilities to check what's available
    if let Some(capabilities) = client.server_capabilities().await {
        if capabilities.tools.is_some() {
            println!("Server supports tools");
        }
    }
    
    Ok(())
}

Alternative: Using ToolBuilder (Advanced)

use mcp_protocol_sdk::core::tool::ToolBuilder;

// Create tools with advanced features and validation
let tool = ToolBuilder::new("enhanced_calculator")
    .description("Advanced calculator with validation")
    .version("1.0.0")
    .schema(json!({
        "type": "object",
        "properties": {
            "a": {"type": "number"},
            "b": {"type": "number"}
        },
        "required": ["a", "b"]
    }))
    .strict_validation()
    .read_only()
    .idempotent()
    .cacheable()
    .build(CalculatorHandler)?;

⚠️ Important API Notes

Server Requirements

• Tool Handlers: Must implement the ToolHandler trait with async fn call()
• String Parameters: Server and tool names require String, not &str
• JSON Schemas: Tools require explicit JSON schema definitions
• Async Traits: Use #[async_trait] for all handler implementations

Getting Started Tips

1. Start with STDIO: Easiest transport for Claude Desktop integration
2. Implement ToolHandler: Required for all tools - no closure shortcuts
3. Handle Errors: Use McpResult<T> and proper error handling
4. Add Dependencies: Don't forget async-trait, tokio, and serde_json

🎯 Use Cases

🏗️ 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:

Minimal Example (STDIO only):

mcp-protocol-sdk = { version = "0.5.0", 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-06-18), 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: 299 tests passing with 100.0% compliance rate 🎉

📊 Schema Compliance Report

🚀 2025-06-18 Features

Full support for all latest MCP protocol enhancements:

• 🎵 Audio Content - Native audio message support
• 📝 Enhanced Tool Results - Structured content alongside text blocks
• 🌐 Enhanced Resources - Rich metadata with title and meta fields
• 🛠️ Advanced Tool Management - Complete tool discovery and categorization
• 📊 Enhanced Progress - Detailed progress tracking
• 🔄 JSON-RPC Batching - Efficient bulk operations
• 📦 Zero Breaking Changes - Full backward compatibility maintained

🧪 Validation Architecture

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

// All types are schema-compliant by construction
let tool_info = ToolInfo {
    name: "calculator".to_string(),
    description: Some("Performs mathematical operations".to_string()),
    input_schema: ToolInputSchema {
        schema_type: "object".to_string(),
        properties: Some(std::collections::HashMap::new()),
        required: Some(vec!["a".to_string(), "b".to_string()]),
        additional_properties: std::collections::HashMap::new(),
    },
    annotations: None,
    title: None,
    meta: None,
};

// JSON serialization matches schema exactly
let json = serde_json::to_value(&tool_info)?;

🔍 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

🌍 Multi-Platform Support

💻 Supported Platforms

🚀 Cross-Compilation

# Add targets for cross-compilation
rustup target add aarch64-apple-darwin      # macOS Apple Silicon
rustup target add x86_64-pc-windows-gnu     # Windows GNU
rustup target add x86_64-unknown-linux-musl # Linux static
rustup target add aarch64-unknown-linux-gnu # Linux ARM64

# Build for different platforms
cargo build --target aarch64-apple-darwin
cargo build --target x86_64-unknown-linux-musl

🔧 Platform-Specific Features

• Process Management: Native tokio::process on all platforms
• File System: Platform-aware path handling and permissions
• TLS/SSL: OpenSSL on Linux, native TLS on macOS/Windows
• Performance: Optimized builds for each architecture

📖 Complete Platform Guide

🌍 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

🛠️ Development

Prerequisites

• Rust 1.85+
• 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