Crate turbomcp_client 

TurboMCP Client

MCP (Model Context Protocol) client implementation for connecting to MCP servers and consuming their capabilities (tools, prompts, resources, and sampling).

Features

• Connection management with automatic reconnection
• Error handling and recovery mechanisms
• Support for all MCP capabilities including bidirectional sampling
• Elicitation response handling for server-initiated user input requests
• Transport-agnostic design (works with any Transport implementation)
• Type-safe protocol communication
• Request/response correlation tracking
• Timeout and cancellation support
• Automatic capability negotiation
• Handler support for server-initiated requests (sampling and elicitation)

Architecture

The client follows a layered architecture:

Application Layer
       ↓
Client API (this crate)
       ↓  
Protocol Layer (turbomcp-protocol)
       ↓
Transport Layer (turbomcp-transport)

Usage

use turbomcp_client::{Client, ClientBuilder};
use turbomcp_transport::stdio::StdioTransport;

// Create a client with stdio transport
let transport = StdioTransport::new();
let mut client = Client::new(transport);

// Initialize connection and negotiate capabilities
let result = client.initialize().await?;
println!("Connected to: {}", result.server_info.name);

// List and call tools
let tools = client.list_tools().await?;
for tool in tools {
    println!("Tool: {} - {}", tool.name, tool.description.as_deref().unwrap_or("No description"));
}

// Access resources
let resources = client.list_resources().await?;
for resource in resources {
    println!("Resource: {}", resource);
}

Elicitation Response Handling (New in 1.0.3)

The client now supports handling server-initiated elicitation requests:

use turbomcp_client::Client;
use std::collections::HashMap;

// Simple elicitation handling example
async fn handle_server_elicitation() {
    // When server requests user input, you would:
    // 1. Present the schema to the user
    // 2. Collect their input  
    // 3. Send response back to server
     
    let user_preferences: HashMap<String, String> = HashMap::new();
    // Your UI/CLI interaction logic here
    println!("Server requesting user preferences");
}

Sampling Support (New in 1.0.3)

Handle server-initiated sampling requests for LLM capabilities:

use turbomcp_client::Client;
use turbomcp_client::sampling::SamplingHandler;
use turbomcp_protocol::types::{CreateMessageRequest, CreateMessageResult};
use async_trait::async_trait;

#[derive(Debug)]
struct MySamplingHandler {
    // Your LLM client would go here
}

#[async_trait]
impl SamplingHandler for MySamplingHandler {
    async fn handle_create_message(
        &self,
        request: CreateMessageRequest
    ) -> Result<CreateMessageResult, Box<dyn std::error::Error + Send + Sync>> {
        // Forward to your LLM provider (OpenAI, Anthropic, etc.)
        // This enables the server to request LLM sampling through the client
         
        Ok(CreateMessageResult {
            role: turbomcp_protocol::types::Role::Assistant,
            content: turbomcp_protocol::types::Content::Text(
                turbomcp_protocol::types::TextContent {
                    text: "Response from LLM".to_string(),
                    annotations: None,
                    meta: None,
                }
            ),
            model: Some("gpt-4".to_string()),
            stop_reason: Some("end_turn".to_string()),
            _meta: None,
        })
    }
}

Error Handling

The client provides comprehensive error handling with automatic retry logic:

match client.call_tool("my_tool", None).await {
    Ok(result) => println!("Tool result: {:?}", result),
    Err(e) => eprintln!("Tool call failed: {}", e),
}

Modules

handlers

Handler traits for bidirectional communication in MCP client

llm

Enhanced LLM Integration System

plugins

Plugin system for TurboMCP client

sampling

MCP-Compliant Client-Side Sampling Support

Macros

with_plugins

Execute a protocol call with full plugin middleware support

with_plugins_list

Execute plugin middleware for methods that return lists (common pattern)

with_simple_plugins

Execute a simple protocol call with plugin middleware for methods without complex request data

Structs

Client

MCP client for communicating with servers

ClientBuilder

Builder for configuring and creating MCP clients

ClientCapabilities

Client capability configuration

ConnectionConfig

Connection configuration for the client

InitializeResult

Result of client initialization

PublicServerCapabilities

Server capabilities per MCP 2025-06-18 specification

SharedClient

Thread-safe wrapper for sharing Client across async tasks