Struct McpClientHandler 

pub struct McpClientHandler { /* private fields */ }

Available on crate feature rmcp only.

An MCP client handler that automatically re-fetches the tool list when the server sends a notifications/tools/list_changed notification.

This handler implements rmcp::ClientHandler and bridges the MCP notification lifecycle with Rig’s ToolServer. When the MCP server’s available tools change, this handler:

1. Re-fetches the full tool list from the MCP server
2. Replaces or removes registrations still owned by this handler
3. Leaves newer local and peer-handler same-name registrations intact

Usage

Use McpClientHandler::connect for a streamlined setup that handles connection, initial tool fetch, and registration in one call:

let tool_server_handle = ToolServer::new().run();
let handler = McpClientHandler::new(client_info, tool_server_handle.clone());
let mcp_service = handler.connect(transport).await?;

The returned RunningService keeps the MCP connection alive. When the server updates its tools, the handler automatically syncs with the tool server.

Implementations

impl McpClientHandler

pub fn new( client_info: ClientInfo, tool_server_handle: ToolServerHandle, ) -> Self

Create a new handler with the given client info and tool server handle.

The tool_server_handle should be a clone of the handle used by the agent, so that tool updates are reflected in agent requests. Registered tools get DEFAULT_MCP_TOOL_TIMEOUT; change it with McpClientHandler::with_timeout.

pub fn with_timeout(self, timeout: impl Into<Option<Duration>>) -> Self

Set (or clear) the per-call timeout applied to every MCP tool this handler registers. Pass a Duration to bound calls, or None to disable.

This applies the same setting to every tool managed by the handler.

pub fn with_refresh_timeout(self, timeout: Duration) -> Self

Set the deadline for initial and list-changed tool-list fetches.

pub async fn connect<T, E, A>( self, transport: T, ) -> Result<RunningService<RoleClient, Self>, McpClientError>

where T: IntoTransport<RoleClient, E, A>, E: Error + Send + Sync + 'static,

Connect to an MCP server, fetch the initial tool list, and register all tools with the tool server.

Returns the running MCP service. The connection stays alive as long as the returned RunningService is held. When the server sends notifications/tools/list_changed, this handler automatically re-fetches and re-registers tools.

Errors

Returns McpClientError if the connection or initial tool fetch fails.

Trait Implementations

impl ClientHandler for McpClientHandler

fn get_info(&self) -> ClientInfo

async fn on_tool_list_changed(&self, context: NotificationContext<RoleClient>)

fn ping( &self, context: RequestContext<RoleClient>, ) -> impl Future<Output = Result<(), ErrorData>> + MaybeSendFuture

fn create_message( &self, params: CreateMessageRequestParams, context: RequestContext<RoleClient>, ) -> impl Future<Output = Result<CreateMessageResult, ErrorData>> + MaybeSendFuture

fn list_roots( &self, context: RequestContext<RoleClient>, ) -> impl Future<Output = Result<ListRootsResult, ErrorData>> + MaybeSendFuture

fn create_elicitation( &self, request: ElicitRequestParams, context: RequestContext<RoleClient>, ) -> impl Future<Output = Result<ElicitResult, ErrorData>> + MaybeSendFuture

Handle an elicitation request from a server asking for user input.

fn on_custom_request( &self, request: CustomRequest, context: RequestContext<RoleClient>, ) -> impl Future<Output = Result<CustomResult, ErrorData>> + MaybeSendFuture

fn on_cancelled( &self, params: CancelledNotificationParam, context: NotificationContext<RoleClient>, ) -> impl Future<Output = ()> + MaybeSendFuture

fn on_progress( &self, params: ProgressNotificationParam, context: NotificationContext<RoleClient>, ) -> impl Future<Output = ()> + MaybeSendFuture

fn on_logging_message( &self, params: LoggingMessageNotificationParam, context: NotificationContext<RoleClient>, ) -> impl Future<Output = ()> + MaybeSendFuture

fn on_resource_updated( &self, params: ResourceUpdatedNotificationParam, context: NotificationContext<RoleClient>, ) -> impl Future<Output = ()> + MaybeSendFuture

fn on_resource_list_changed( &self, context: NotificationContext<RoleClient>, ) -> impl Future<Output = ()> + MaybeSendFuture

fn on_prompt_list_changed( &self, context: NotificationContext<RoleClient>, ) -> impl Future<Output = ()> + MaybeSendFuture

fn on_url_elicitation_notification_complete( &self, params: ElicitationResponseNotificationParam, context: NotificationContext<RoleClient>, ) -> impl Future<Output = ()> + MaybeSendFuture

fn on_task_status( &self, params: TaskStatusNotificationParam, context: NotificationContext<RoleClient>, ) -> impl Future<Output = ()> + MaybeSendFuture

fn on_custom_notification( &self, notification: CustomNotification, context: NotificationContext<RoleClient>, ) -> impl Future<Output = ()> + MaybeSendFuture