Mcp Protocol Sdk

MCP Protocol SDK

[](https://crates.io/crates/mcp-protocol-sdk) [](https://docs.rs/mcp-protocol-sdk) [](https://opensource.org/licenses/MIT) [](https://crates.io/crates/mcp-protocol-sdk)

[](https://github.com/mcp-rust/mcp-protocol-sdk/actions/workflows/ci.yml) [](https://github.com/mcp-rust/mcp-protocol-sdk/actions/workflows/security.yml) [](https://github.com/mcp-rust/mcp-protocol-sdk/actions/workflows/dependencies.yml) [](https://github.com/mcp-rust/mcp-protocol-sdk/actions/workflows/docs.yml) [](https://github.com/mcp-rust/mcp-protocol-sdk/actions/workflows/benchmarks.yml) [](https://github.com/mcp-rust/mcp-protocol-sdk/actions/workflows/release.yml)

[](https://codecov.io/gh/mcp-rust/mcp-protocol-sdk) [](#-mcp-protocol-schema-compliance) [](https://github.com/mcp-rust/mcp-protocol-sdk/actions/workflows/ci.yml) [](https://www.rust-lang.org)

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

> 🚀 Quick Start: [Getting Started](./docs/getting-started.md) | [Implementation Guide](./docs/implementation-guide.md) | [Examples](./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](./docs/README.md) | 📖 API Reference | 🚀 [Getting Started](./docs/getting-started.md) | 🆚 [vs Official SDK](./docs/comparison-official-sdk.md)

🎯 Quick Links: 📖 [Implementation Guide](./docs/implementation-guide.md) | 🌍 [Platform Support](./docs/platform-support.md) | 🔧 [Examples](./examples/) | 🚀 [Transports](./docs/transports.md)

---

✨ 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) -> McpResult {
        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> {
    // 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> {
    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 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](./docs/integrations/claude-desktop.md) | | ⚡ Cursor IDE Enhancement | AI-powered development tools | [📝 Guide](./docs/integrations/cursor.md) | | 📝 VS Code Extensions | Smart code assistance and automation | [📝 Guide](./docs/integrations/vscode.md) | | 🗄️ 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](./docs/transports.md)

📋 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](./docs/SCHEMA_COMPLIANCE.md)

🌍 Multi-Platform Support

💻 Supported Platforms

| Platform | Architecture | Testing | Status | |----------|-------------|---------|--------| | Linux | x8664, ARM64, musl | ✅ Automated | ✅ Production Ready | | macOS | Intel, Apple Silicon | ✅ Automated | ✅ Production Ready | | Windows | x8664, 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

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [prismworks-ai](https://github.com/prismworks-ai)
- **Source:** [prismworks-ai/mcp-protocol-sdk](https://github.com/prismworks-ai/mcp-protocol-sdk)
- **License:** MIT

Install and usage instructions live in the source repository linked above.