mcp-protocol-sdk

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

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

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-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

Platform	Architecture	Testing	Status
Linux	x86_64, ARM64, musl	✅ Automated	✅ Production Ready
macOS	Intel, Apple Silicon	✅ Automated	✅ Production Ready
Windows	x86_64, GNU	✅ Automated	✅ Production Ready

🚀 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

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
Basic Client	Basic client usage	STDIO	Client patterns

🛠️ 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

---