Struct ClientBuilder 

pub struct ClientBuilder { /* private fields */ }

Builder for configuring and creating MCP clients

Provides a fluent interface for configuring client options before creation. The enhanced builder pattern supports comprehensive configuration including:

• Protocol capabilities
• Plugin registration
• Handler registration
• Connection settings
• Resilience configuration

Examples

Basic usage:

use turbomcp_client::ClientBuilder;
use turbomcp_transport::stdio::StdioTransport;

let client = ClientBuilder::new()
    .with_tools(true)
    .with_prompts(true)
    .with_resources(false)
    .build(StdioTransport::new());

Advanced configuration:

use turbomcp_client::{ClientBuilder, ConnectionConfig};
use turbomcp_client::plugins::{MetricsPlugin, PluginConfig};
use turbomcp_transport::stdio::StdioTransport;
use std::sync::Arc;

let client = ClientBuilder::new()
    .with_tools(true)
    .with_prompts(true)
    .with_resources(true)
    .with_sampling(true)
    .with_connection_config(ConnectionConfig {
        timeout_ms: 60_000,
        max_retries: 5,
        retry_delay_ms: 2_000,
        keepalive_ms: 30_000,
    })
    .with_plugin(Arc::new(MetricsPlugin::new(PluginConfig::Metrics)))
    .build(StdioTransport::new())
    .await?;

Implementations

impl ClientBuilder

pub fn new() -> ClientBuilder

Create a new client builder

Returns a new builder with default configuration.

pub fn with_tools(self, enabled: bool) -> ClientBuilder

Enable or disable tool support

Arguments

• enabled - Whether to enable tool support

pub fn with_prompts(self, enabled: bool) -> ClientBuilder

Enable or disable prompt support

Arguments

• enabled - Whether to enable prompt support

pub fn with_resources(self, enabled: bool) -> ClientBuilder

Enable or disable resource support

Arguments

• enabled - Whether to enable resource support

pub fn with_sampling(self, enabled: bool) -> ClientBuilder

Enable or disable sampling support

Arguments

• enabled - Whether to enable sampling support

pub fn with_max_concurrent_handlers(self, limit: usize) -> ClientBuilder

Set maximum concurrent request/notification handlers

This limits how many server-initiated requests/notifications can be processed simultaneously. Provides automatic backpressure when the limit is reached.

Arguments

• limit - Maximum concurrent handlers (default: 100)

Tuning Guide

• Low-resource clients: 50
• Standard clients: 100 (default)
• High-performance: 200-500
• Maximum recommended: 1000

Example

use turbomcp_client::ClientBuilder;

let builder = ClientBuilder::new()
    .with_max_concurrent_handlers(200);

pub fn with_capabilities( self, capabilities: ClientCapabilities, ) -> ClientBuilder

Configure all capabilities at once

Arguments

• capabilities - The capabilities configuration

pub fn with_connection_config(self, config: ConnectionConfig) -> ClientBuilder

Configure connection settings

Arguments

• config - The connection configuration

pub fn with_timeout(self, timeout_ms: u64) -> ClientBuilder

Set request timeout

Arguments

• timeout_ms - Timeout in milliseconds

pub fn with_max_retries(self, max_retries: u32) -> ClientBuilder

Set maximum retry attempts

Arguments

• max_retries - Maximum number of retries

pub fn with_retry_delay(self, delay_ms: u64) -> ClientBuilder

Set retry delay

Arguments

• delay_ms - Retry delay in milliseconds

pub fn with_keepalive(self, interval_ms: u64) -> ClientBuilder

Set keep-alive interval

Arguments

• interval_ms - Keep-alive interval in milliseconds

pub fn enable_resilience(self) -> ClientBuilder

Enable resilient transport with circuit breaker, retry, and health checking

When enabled, the transport layer will automatically:

• Retry failed operations with exponential backoff
• Use circuit breaker pattern to prevent cascade failures
• Perform periodic health checks
• Deduplicate messages

Examples

use turbomcp_client::ClientBuilder;
use turbomcp_transport::stdio::StdioTransport;

let client = ClientBuilder::new()
    .enable_resilience()
    .build(StdioTransport::new());

pub fn with_retry_config(self, config: RetryConfig) -> ClientBuilder

Configure retry behavior for resilient transport

Arguments

• config - Retry configuration

Examples

use turbomcp_client::ClientBuilder;
use turbomcp_transport::resilience::RetryConfig;
use turbomcp_transport::stdio::StdioTransport;
use std::time::Duration;

let client = ClientBuilder::new()
    .enable_resilience()
    .with_retry_config(RetryConfig {
        max_attempts: 5,
        base_delay: Duration::from_millis(100),
        max_delay: Duration::from_secs(30),
        backoff_multiplier: 2.0,
        jitter_factor: 0.1,
        retry_on_connection_error: true,
        retry_on_timeout: true,
        custom_retry_conditions: Vec::new(),
    })
    .build(StdioTransport::new());

pub fn with_circuit_breaker_config( self, config: CircuitBreakerConfig, ) -> ClientBuilder

Configure circuit breaker for resilient transport

Arguments

• config - Circuit breaker configuration

Examples

use turbomcp_client::ClientBuilder;
use turbomcp_transport::resilience::CircuitBreakerConfig;
use turbomcp_transport::stdio::StdioTransport;
use std::time::Duration;

let client = ClientBuilder::new()
    .enable_resilience()
    .with_circuit_breaker_config(CircuitBreakerConfig {
        failure_threshold: 5,
        success_threshold: 2,
        timeout: Duration::from_secs(60),
        rolling_window_size: 100,
        minimum_requests: 10,
    })
    .build(StdioTransport::new());

pub fn with_health_check_config( self, config: HealthCheckConfig, ) -> ClientBuilder

Configure health checking for resilient transport

Arguments

• config - Health check configuration

Examples

use turbomcp_client::ClientBuilder;
use turbomcp_transport::resilience::HealthCheckConfig;
use turbomcp_transport::stdio::StdioTransport;
use std::time::Duration;

let client = ClientBuilder::new()
    .enable_resilience()
    .with_health_check_config(HealthCheckConfig {
        interval: Duration::from_secs(30),
        timeout: Duration::from_secs(5),
        failure_threshold: 3,
        success_threshold: 1,
        custom_check: None,
    })
    .build(StdioTransport::new());

pub fn with_plugin(self, plugin: Arc<dyn ClientPlugin>) -> ClientBuilder

Register a plugin with the client

Plugins provide middleware functionality for request/response processing, metrics collection, retry logic, caching, and other cross-cutting concerns.

Arguments

• plugin - The plugin implementation

Examples

use turbomcp_client::{ClientBuilder, ConnectionConfig};
use turbomcp_client::plugins::{MetricsPlugin, RetryPlugin, PluginConfig, RetryConfig};
use std::sync::Arc;

let client = ClientBuilder::new()
    .with_plugin(Arc::new(MetricsPlugin::new(PluginConfig::Metrics)))
    .with_plugin(Arc::new(RetryPlugin::new(PluginConfig::Retry(RetryConfig {
        max_retries: 5,
        base_delay_ms: 1000,
        max_delay_ms: 30000,
        backoff_multiplier: 2.0,
        retry_on_timeout: true,
        retry_on_connection_error: true,
    }))));

pub fn with_plugins(self, plugins: Vec<Arc<dyn ClientPlugin>>) -> ClientBuilder

Register multiple plugins at once

Arguments

• plugins - Vector of plugin implementations

pub fn with_elicitation_handler( self, handler: Arc<dyn ElicitationHandler>, ) -> ClientBuilder

Register an elicitation handler for processing user input requests

Arguments

• handler - The elicitation handler implementation

pub fn with_log_handler(self, handler: Arc<dyn LogHandler>) -> ClientBuilder

Register a log handler for processing server log messages

Arguments

• handler - The log handler implementation

pub fn with_resource_update_handler( self, handler: Arc<dyn ResourceUpdateHandler>, ) -> ClientBuilder

Register a resource update handler for processing resource change notifications

Arguments

• handler - The resource update handler implementation

pub async fn build<T>(self, transport: T) -> Result<Client<T>, Box<Error>>

where T: Transport + 'static,

Build a client with the configured options

Creates a new client instance with all the configured options. The client will be initialized with the registered plugins, handlers, and providers.

Arguments

• transport - The transport to use for the client

Returns

Returns a configured Client instance wrapped in a Result for async setup.

Examples

use turbomcp_client::ClientBuilder;
use turbomcp_transport::stdio::StdioTransport;

let client = ClientBuilder::new()
    .with_tools(true)
    .with_prompts(true)
    .build(StdioTransport::new())
    .await?;

pub async fn build_resilient<T>( self, transport: T, ) -> Result<Client<TurboTransport>, Box<Error>>

where T: Transport + 'static,

Build a client with resilient transport (circuit breaker, retry, health checking)

When resilience features are enabled via enable_resilience() or any resilience configuration method, this wraps the transport in a TurboTransport that provides:

• Automatic retry with exponential backoff
• Circuit breaker pattern for fast failure
• Health checking and monitoring
• Message deduplication

Arguments

• transport - The base transport to wrap with resilience features

Returns

Returns a configured Client<TurboTransport> instance.

Errors

Returns an error if plugin initialization fails.

Examples

use turbomcp_client::ClientBuilder;
use turbomcp_transport::stdio::StdioTransport;
use turbomcp_transport::resilience::{RetryConfig, CircuitBreakerConfig, HealthCheckConfig};
use std::time::Duration;

let client = ClientBuilder::new()
    .with_retry_config(RetryConfig {
        max_attempts: 5,
        base_delay: Duration::from_millis(200),
        ..Default::default()
    })
    .with_circuit_breaker_config(CircuitBreakerConfig {
        failure_threshold: 3,
        timeout: Duration::from_secs(30),
        ..Default::default()
    })
    .with_health_check_config(HealthCheckConfig {
        interval: Duration::from_secs(15),
        timeout: Duration::from_secs(5),
        ..Default::default()
    })
    .build_resilient(StdioTransport::new())
    .await?;

pub fn build_sync<T>(self, transport: T) -> Client<T>

where T: Transport + 'static,

Build a client synchronously with basic configuration only

This is a convenience method for simple use cases where no async setup is required. For advanced features like plugins, use build() instead.

Arguments

• transport - The transport to use for the client

Returns

Returns a configured Client instance.

Examples

use turbomcp_client::ClientBuilder;
use turbomcp_transport::stdio::StdioTransport;

let client = ClientBuilder::new()
    .with_tools(true)
    .build_sync(StdioTransport::new());

pub fn capabilities(&self) -> &ClientCapabilities

Get the current capabilities configuration

pub fn connection_config(&self) -> &ConnectionConfig

Get the current connection configuration

pub fn plugin_count(&self) -> usize

Get the number of registered plugins

pub fn has_handlers(&self) -> bool

Check if any handlers are registered

Trait Implementations

impl Debug for ClientBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for ClientBuilder

fn default() -> ClientBuilder

Returns the “default value” for a type.