Crate turbomcp_server 

TurboMCP Server

MCP (Model Context Protocol) server implementation with graceful shutdown, routing, lifecycle management, and comprehensive observability features.

Features

• Roots Configuration - Configurable filesystem roots via builder API or macro
• Elicitation Support - Server-initiated requests for interactive user input
• Sampling Protocol - Bidirectional LLM sampling with client interaction
• Graceful Shutdown - Shutdown handling with signal support
• Multi-Transport - STDIO, TCP, Unix, WebSocket, HTTP/SSE support
• Middleware Stack - Authentication, rate limiting, and security headers
• Request Routing - Efficient handler registration and dispatch
• Health Monitoring - Comprehensive health checks and metrics
• Error Recovery - Robust error handling and recovery mechanisms
• MCP Compliance - Full support for tools, prompts, resources, roots, sampling, and elicitation
• Server-Initiated Requests - Support for sampling and elicitation via ServerCapabilities

Example

use turbomcp_server::ServerBuilder;
use turbomcp_protocol::types::Root;
use tokio::signal;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let server = ServerBuilder::new()
        .name("MyServer")
        .version("1.0.0")
        // Configure filesystem roots
        .root("file:///workspace", Some("Workspace".to_string()))
        .root("file:///tmp", Some("Temp".to_string()))
        .build();
     
    // Get shutdown handle for graceful termination
    let shutdown_handle = server.shutdown_handle();
     
    // In production: spawn server and wait for shutdown
    // tokio::spawn(async move { server.run_stdio().await });
    // signal::ctrl_c().await?;
    // shutdown_handle.shutdown().await;
     
    Ok(())
}

Elicitation Support

The server includes comprehensive elicitation support for interactive user input:

• ElicitationCoordinator for managing elicitation lifecycle
• Request/response correlation with timeouts
• Retry logic with configurable attempts
• Priority-based request queuing
• Automatic cleanup of expired requests

Sampling Support

The server provides built-in support for server-initiated sampling requests to clients:

use turbomcp_server::sampling::SamplingExt;
use turbomcp_protocol::RequestContext;
use turbomcp_protocol::types::{CreateMessageRequest, SamplingMessage, Role, Content, TextContent};

async fn my_tool(ctx: RequestContext) -> Result<String, Box<dyn std::error::Error>> {
    // Create a sampling request
    let request = CreateMessageRequest {
        messages: vec![SamplingMessage {
            role: Role::User,
            content: Content::Text(TextContent {
                text: "What is 2+2?".to_string(),
                annotations: None,
                meta: None,
            }),
            metadata: None,
        }],
        max_tokens: 50,
        model_preferences: None,
        system_prompt: Some("You are a helpful math assistant.".to_string()),
        include_context: Some(turbomcp_protocol::types::IncludeContext::None),
        temperature: Some(0.7),
        stop_sequences: None,
        _meta: None,
    };

    // Send the request to the client
    let result = ctx.create_message(request).await?;
    Ok(format!("Response: {:?}", result))
}

Sampling Features:

• Client-side sampling configuration support
• Server-side sampling metadata tracking
• Integration with elicitation for dynamic sampling decisions
• Configurable timeouts and retry logic

Compile-Time Routing (Experimental)

Zero-cost compile-time router generation for high-throughput scenarios:

• Zero-cost compile-time router generation
• Type-safe route matching at compile time
• Automatic handler registration through macros
• Performance optimization for high-throughput scenarios

Note: Compile-time routing is experimental and may have limitations with some MCP protocol methods.

Re-exports

pub use config::Configuration;

pub use config::ConfigurationBuilder;

pub use config::ServerConfig;

pub use error::ServerError;

pub use error::ServerResult;

pub use handlers::CompletionHandler;

pub use handlers::ElicitationHandler;

pub use handlers::LoggingHandler;

pub use handlers::PingHandler;

pub use handlers::PromptHandler;

pub use handlers::ResourceHandler;

pub use handlers::ResourceTemplateHandler;

pub use handlers::SamplingHandler;

pub use handlers::ToolHandler;

pub use lifecycle::HealthStatus;

pub use lifecycle::ServerLifecycle;

pub use lifecycle::ShutdownSignal;

pub use metrics::MetricsCollector;

pub use metrics::ServerMetrics;

pub use observability::ObservabilityConfig;

pub use observability::ObservabilityGuard;

pub use observability::OtlpProtocol;

pub use observability::PerformanceMonitor;

pub use observability::SamplingConfig;

pub use observability::SecurityAuditLogger;

pub use observability::global_observability;

pub use registry::HandlerRegistry;

pub use registry::Registry;

pub use registry::RegistryBuilder;

pub use routing::RequestRouter;

pub use routing::Route;

pub use routing::Router;

pub use server::McpServer;

pub use server::ServerBuilder;

pub use server::ShutdownHandle;

pub use elicitation::ElicitationCoordinator;

pub use elicitation::ElicitationTransport;

pub use elicitation::SharedElicitationCoordinator;

Modules

capabilities

Server-to-client request adapter for bidirectional MCP communication.

config

Server configuration management

elicitation

Elicitation support for TurboMCP servers

error

Server error types and handling

handlers

Handler traits and implementations for MCP operations

lifecycle

Server lifecycle management and graceful shutdown

metrics

Production-grade metrics collection and monitoring system

observability

Production-grade OpenTelemetry observability integration

prelude

Prelude for common server functionality

registry

Server-side handler registry for MCP protocol implementation.

routing

Request routing and handler dispatch system

runtime

Runtime components for bidirectional transport

sampling

Server-initiated sampling support for TurboMCP

server

MCP server core implementation

service

Core MCP service implementation using Tower pattern

timeout

Tool timeout and cancellation management

Macros

instrument_async

Helper macro for instrumenting async functions

measure_performance

Helper macro for performance span measurement

Structs

CallToolRequest

A request to execute a specific tool.

CallToolResult

The result of a CallToolRequest.

ClientCapabilities

Client capabilities per MCP 2025-06-18 specification

JsonRpcError

JSON-RPC error object

JsonRpcRequest

JSON-RPC request message

JsonRpcResponse

JSON-RPC response message

JsonRpcVersion

JSON-RPC version type

ListToolsResult

The result of a ListToolsRequest.

RequestContext

Context information for a single MCP request, carried through its entire lifecycle.

ServerCapabilities

Server capabilities per MCP 2025-06-18 specification

Tool

Represents a tool that can be executed by an MCP server, as per the MCP 2025-06-18 specification.

Enums

MessageId

Unique identifier for messages

Constants

SERVER_NAME

Server name

SERVER_VERSION

Server version

Functions

default_config

Default server configuration

server

Create a new server builder