Crate turbomcp

Expand description

§TurboMCP - Model Context Protocol SDK

Rust SDK for the Model Context Protocol (MCP) with zero-boilerplate macros, transport-agnostic design, and WASM support.

§Features

Zero Boilerplate - #[server], #[tool], #[resource], #[prompt] macros
Transport Agnostic - STDIO, HTTP, WebSocket, TCP, Unix sockets
Runtime Selection - Choose transport at runtime without recompilation
BYO Server - Integrate with existing Axum/Tower infrastructure
WASM Ready - no_std compatible core for edge deployment
Type Safe - Automatic JSON schema generation from Rust types

§Quick Start

use turbomcp::prelude::*;

#[derive(Clone)]
struct Calculator;

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

    /// Multiply two numbers
    #[tool]
    async fn multiply(&self, a: i64, b: i64) -> i64 {
        a * b
    }
}

#[tokio::main]
async fn main() {
    Calculator.serve().await.unwrap();
}

§Runtime Transport Selection

use turbomcp::prelude::*;

#[tokio::main]
async fn main() {
    let transport = std::env::var("MCP_TRANSPORT").unwrap_or_default();

    Calculator.builder()
        .transport(match transport.as_str() {
            "http" => Transport::http("0.0.0.0:8080"),
            "ws" => Transport::websocket("0.0.0.0:8080"),
            "tcp" => Transport::tcp("0.0.0.0:9000"),
            _ => Transport::stdio(),
        })
        .serve()
        .await
        .unwrap();
}

§BYO Server (Axum Integration)

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

#[tokio::main]
async fn main() {
    // Get MCP routes as an Axum router
    let mcp = Calculator.builder().into_axum_router();

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

    // Run with your own server
    let listener = tokio::net::TcpListener::bind("0.0.0.0:8080").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

§Feature Flags

Choose the right feature set for your use case:

# Minimal (STDIO only, recommended for CLI tools)
turbomcp = { version = "3.0", default-features = false, features = ["minimal"] }

# Full (all transports)
turbomcp = { version = "3.0", features = ["full"] }

Available features:

stdio - Standard I/O transport (default, works with Claude Desktop)
http - HTTP/SSE transport
websocket - WebSocket bidirectional transport
tcp - Raw TCP socket transport
unix - Unix domain socket transport

Re-exports§

pub use turbomcp_telemetry as telemetry;telemetry

Modules§

prelude: Convenient prelude for TurboMCP applications.
testing: In-memory test client for ergonomic MCP server testing. In-memory test client for ergonomic MCP server testing.

Structs§

CallToolRequest: Request payload for tool invocation A request to execute a specific tool.
CallToolResult: Response payload for tool execution results The result of a CallToolRequest.
ClientCapabilities: Client capability declaration during initialization Client capabilities per MCP 2025-11-25 specification
Image: Image content type for multimodal responses Wrapper for returning base64-encoded image data.
InitializeRequest: Initial handshake request from client to server The initialize request is sent by the client as the first message after connection.
InitializeResult: Initial handshake response with server capabilities The response to a successful initialize request.
Json: JSON content wrapper for structured data responses Wrapper for returning JSON-serialized data from a tool handler.
JsonRpcError: JSON-RPC 2.0 error object JSON-RPC error object
JsonRpcNotification: JSON-RPC 2.0 notification (no response expected) JSON-RPC notification message (no response expected)
JsonRpcRequest: JSON-RPC 2.0 request message JSON-RPC request message
JsonRpcResponse: JSON-RPC 2.0 response message JSON-RPC response message
McpError: Unified MCP error type
Message: A message in a prompt (PromptMessage per spec).
Prompt: Prompt definition.
PromptArgument: Argument definition for prompts.
PromptResult: Result from getting a prompt.
RequestContext: Minimal request context that works on all platforms.
Resource: Resource definition.
ResourceLink: A resource link (reference without embedding contents).
ResourceResult: Result from reading a resource.
ServerBuilder: Builder for configuring and launching MCP servers with transports Server builder for configuring and running MCP servers.
ServerCapabilities: Server capability declaration during initialization Server capabilities per MCP 2025-11-25 specification
ServerConfig: Configuration for MCP server behavior, timeouts, and protocol versions Server configuration.
ServerConfigBuilder: Builder for constructing ServerConfig with type-safe defaults Builder for server configuration.
ServerInfo: Server information for MCP initialization.
Text: Text content type for string responses Wrapper for explicitly returning text content.
Tool: Tool definition.
ToolError: Tool execution error with code and message Error type for tool handlers that supports the ? operator.
ToolInputSchema: JSON Schema for tool input parameters.
ToolResult: Result from calling a tool.

Enums§

MessageId: Unique identifier for correlating requests and responses Unique identifier for messages
ResourceContents: Contents of a resource (text or binary).
Role: Role in a conversation or prompt message.
SamplingContent: Content block for sampling messages (SamplingMessageContentBlock per spec).
SamplingContentBlock: Wrapper that deserializes as either a single content block or an array.
Transport: Transport configuration enum for runtime transport selection Transport configuration for the server.

Constants§

CRATE_NAME: TurboMCP crate name
VERSION: TurboMCP version from Cargo.toml

Traits§

IntoPromptResult: Convert any type to a PromptResult.
IntoResourceResult: Convert any type to a ResourceResult.
IntoToolError: Trait for converting errors into tool error responses Convenience trait for converting to ToolError with context.
IntoToolResponse: Trait for converting values into tool responses Trait for types that can be converted into a tool response.
IntoToolResult: Convert any type to a ToolResult.
McpHandler: The unified MCP handler trait.
McpHandlerExt: Extension trait providing transport-specific serve methods (serve_stdio, serve_http, etc.) Extension trait for running McpHandler on various transports.
McpServerExt: Extension trait for MCP server operations Extension trait for creating server builders from handlers.

Type Aliases§

McpResult: Result type alias for MCP operations

Attribute Macros§

description: Provides a description for a tool parameter.
prompt: Marks a method as a prompt handler within a #[server] block.
resource: Marks a method as a resource handler within a #[server] block.
server: Marks an impl block as an MCP server with automatic McpHandler implementation.
tool: Marks a method as a tool handler within a #[server] block.

Crate turbomcp

Crate turbomcp Copy item path

§TurboMCP - Model Context Protocol SDK

§Features

§Quick Start

§Runtime Transport Selection

§BYO Server (Axum Integration)

§Feature Flags

Re-exports§

Modules§

Structs§

Enums§

Constants§

Traits§

Type Aliases§

Attribute Macros§

Crate turbomcp