TurboMCP Server

Server framework for the Model Context Protocol. Provides the McpHandlerExt entry points, the ServerBuilder for runtime transport selection, typed middleware (McpMiddleware / MiddlewareStack), configuration types (ServerConfig, ProtocolConfig, rate limits, connection limits, origin validation), and the JSON-RPC router shared by every transport.

Table of Contents

• Overview
• Quick Start
• Server Builder
• Server Configuration
• Protocol Version Negotiation
• Middleware
• Transports
• Feature Flags
• Related Crates

Overview

turbomcp-server is a Layer 5 crate that turns any McpHandler (implemented by the #[server] macro, CompositeHandler, or a hand-written type) into a running MCP server. It owns:

• Entry points (McpHandlerExt::run, run_stdio, run_http, run_tcp, run_unix, run_websocket, handle_request).
• The ServerBuilder fluent API for runtime transport and config selection.
• The JSON-RPC router (router::route_request et al.) shared by all transports.
• ServerConfig and its validated builder (try_build) plus ProtocolConfig for version negotiation.
• The typed McpMiddleware trait and MiddlewareStack<H> composition wrapper.
• Progressive disclosure (VisibilityLayer) and server composition (CompositeHandler).

Authentication (OAuth 2.1 / JWT / API keys) lives in turbomcp-auth. Telemetry lives in turbomcp-telemetry. Session management lives in turbomcp-protocol. This crate does not bundle them.

Quick Start

Any type that implements McpHandler (the #[server] macro generates one for you) gets the run* and builder() methods automatically via blanket impls.

use turbomcp::prelude::*;

#[derive(Clone)]
struct Calculator;

#[server(name = "calculator", version = "1.0.0")]
impl Calculator {
    /// Add two numbers
    #[tool]
    async fn add(&self, a: i64, b: i64) -> i64 { a + b }
}

#[tokio::main]
async fn main() -> McpResult<()> {
    // STDIO by default
    Calculator.run().await
}

Server Builder

ServerBuilder<H> is obtained via McpServerExt::builder() (blanket impl on every McpHandler). The methods available on it:

use std::time::Duration;
use turbomcp::prelude::*;

#[tokio::main]
async fn main() -> McpResult<()> {
    Calculator.builder()
        .transport(Transport::http("0.0.0.0:8080"))
        .with_rate_limit(100, Duration::from_secs(1))
        .with_connection_limit(1000)
        .with_graceful_shutdown(Duration::from_secs(30))
        .serve()
        .await
}

BYO server (Axum integration)

use axum::{Router, routing::get};
use turbomcp::prelude::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mcp = Calculator.builder().into_axum_router();

    let app = Router::new()
        .route("/health", get(|| async { "OK" }))
        .merge(mcp);

    let listener = tokio::net::TcpListener::bind("0.0.0.0:8080").await?;
    axum::serve(listener, app).await?;
    Ok(())
}

Server Configuration

ServerConfig is constructed through ServerConfig::builder(). Fields:

Use .build() for an infallible build with defaults, or .try_build() to validate. try_build() returns ConfigValidationError when:

• max_message_size is below 1024 bytes
• RateLimitConfig::max_requests is 0
• RateLimitConfig::window is Duration::ZERO
• All four fields of ConnectionLimits are 0

use std::time::Duration;
use turbomcp_server::{ServerConfig, RateLimitConfig};

let config = ServerConfig::builder()
    .max_message_size(1024 * 1024)
    .rate_limit(RateLimitConfig::new(100, Duration::from_secs(1)))
    .try_build()
    .expect("invalid server configuration");

Protocol Version Negotiation

ProtocolConfig controls which MCP spec versions the server accepts. Fields: preferred_version: ProtocolVersion, supported_versions: Vec<ProtocolVersion>, allow_fallback: bool.

Default (as of v3.1): preferred_version = ProtocolVersion::LATEST, supported_versions = ProtocolVersion::STABLE.to_vec() (all stable spec versions), allow_fallback = false. Older clients are accepted and responses are filtered through the appropriate version adapter.

Use ProtocolConfig::strict(version) to restore exact-match negotiation against a single version. Use ProtocolConfig::multi_version() to construct the default multi-version config explicitly.

use turbomcp::prelude::*;
use turbomcp_server::config::ProtocolVersion;

// Exact-match against the latest version only
Calculator.builder()
    .with_protocol(ProtocolConfig::strict(ProtocolVersion::LATEST.clone()))
    .serve().await?;

// Explicit multi-version (same as default)
Calculator.builder()
    .with_protocol(ProtocolConfig::multi_version())
    .serve().await?;

ProtocolConfig::negotiate(client_version) returns the negotiated ProtocolVersion or None if no compatible version is found (and fallback is disabled).

Middleware

Middleware is typed around the MCP operation set. Implement McpMiddleware and layer it onto any McpHandler via MiddlewareStack:

use turbomcp_server::{McpMiddleware, MiddlewareStack, Next, McpServerExt};
use turbomcp_core::context::RequestContext;
use turbomcp_core::error::{McpError, McpResult};
use turbomcp_types::ToolResult;
use serde_json::Value;
use std::future::Future;
use std::pin::Pin;

struct Logging;

impl McpMiddleware for Logging {
    fn on_call_tool<'a>(
        &'a self,
        name: &'a str,
        args: Value,
        ctx: &'a RequestContext,
        next: Next<'a>,
    ) -> Pin<Box<dyn Future<Output = McpResult<ToolResult>> + Send + 'a>> {
        Box::pin(async move {
            tracing::info!(tool = name, "calling");
            next.call_tool(name, args, ctx).await
        })
    }
}

// MiddlewareStack wraps a handler; it itself implements McpHandler,
// so it participates in the same builder / transport pipeline.
let stack = MiddlewareStack::new(Calculator).with_middleware(Logging);
stack.builder().serve().await?;

The trait's other hooks (on_list_tools, on_list_resources, on_list_prompts, on_read_resource, on_get_prompt, etc.) all have pass-through default implementations — override only the ones you need.

Transports

Runtime transport selection is done through Transport. Each variant is gated by the matching feature flag.

Each McpHandler also has direct run_stdio / run_http / run_websocket / run_tcp / run_unix methods (feature-gated) via McpHandlerExt, plus handle_request(Value, RequestContext) for serverless-style one-shot use.

Feature Flags

Related Crates

• turbomcp — Main SDK that re-exports this crate's public API
• turbomcp-core — McpHandler, McpError, JSON-RPC primitives
• turbomcp-protocol — Protocol implementation, session management
• turbomcp-transport — Transport re-export hub
• turbomcp-auth — OAuth 2.1 / JWT / API keys (optional)
• turbomcp-telemetry — OpenTelemetry / Prometheus (optional)

License

Licensed under the MIT License.

Part of the TurboMCP Rust SDK for the Model Context Protocol.