Struct McpToolset 

pub struct McpToolset<S = ()>
where
    S: Service<RoleClient> + Send + Sync + 'static,
{ /* private fields */ }

Available on crate features mcp and tools only.

MCP Toolset - connects to an MCP server and exposes its tools as ADK tools.

This toolset implements the ADK Toolset trait and bridges the gap between MCP servers and ADK agents. It:

1. Connects to an MCP server via the provided transport
2. Discovers available tools from the server
3. Converts MCP tools to ADK-compatible Tool implementations
4. Proxies tool execution calls to the MCP server

Example

use adk_tool::{
    McpToolset,
    mcp::rmcp::{ServiceExt, transport::TokioChildProcess},
};
use tokio::process::Command;

// Create MCP client connection to a local server
let client = ().serve(TokioChildProcess::new(
    Command::new("/opt/company/bin/workspace-mcp")
        .arg("--stdio")
        .arg("--root")
        .arg("/srv/workspace")
)?).await?;

// Create toolset from the client
let toolset = McpToolset::new(client);

// Add to agent
let agent = LlmAgentBuilder::new("assistant")
    .toolset(Arc::new(toolset))
    .build()?;

Implementations

impl<S> McpToolset<S>

where S: Service<RoleClient> + Send + Sync + 'static,

pub fn new(client: RunningService<RoleClient, S>) -> McpToolset<S>

Create a new MCP toolset from a running MCP client service.

The client should already be connected and initialized. Use adk_tool::mcp::rmcp::ServiceExt::serve() to create the client.

Example

use adk_tool::mcp::rmcp::{ServiceExt, transport::TokioChildProcess};
use tokio::process::Command;

let client = ().serve(TokioChildProcess::new(
    Command::new("my-mcp-server")
)?).await?;

let toolset = McpToolset::new(client);

pub fn with_client_handler( client: RunningService<RoleClient, S>, ) -> McpToolset<S>

Create a McpToolset from a RunningService with a custom ClientHandler.

This is functionally identical to new() but makes the intent explicit when using a custom ClientHandler type.

Example

use adk_tool::{McpToolset, mcp::rmcp::ServiceExt};

let client = my_custom_handler.serve(transport).await?;
let toolset = McpToolset::with_client_handler(client);

pub fn with_name(self, name: impl Into<String>) -> McpToolset<S>

Set a custom name for this toolset.

pub fn with_task_support(self, config: McpTaskConfig) -> McpToolset<S>

Enable negotiated MCP task support for long-running operations.

A tool declared with required task support always uses the task flow. A tool declaring optional task support uses it when this configuration is enabled and the server negotiated tasks.requests.tools.call.

Example

let toolset = McpToolset::new(client)
    .with_task_support(McpTaskConfig::enabled()
        .poll_interval(Duration::from_secs(2))
        .timeout(Duration::from_secs(300)));

pub fn with_connection_factory<F>(self, factory: Arc<F>) -> McpToolset<S>

where F: ConnectionFactory<S> + 'static,

Provide a connection factory to enable automatic MCP reconnection.

pub fn with_refresh_config(self, config: RefreshConfig) -> McpToolset<S>

Configure MCP reconnect/retry behavior.

pub fn with_tool_call_retries(self) -> McpToolset<S>

Allow MCP tool calls to be replayed after reconnecting.

A transport failure after request transmission is an ambiguous outcome: a mutating tool may have completed its external effect before the response was lost. Enable this only for read-only tools or operations protected by a stable provider idempotency guarantee. Discovery and resource operations keep their normal reconnect behavior without this.

Example

let toolset = McpToolset::new(client)
    .with_connection_factory(Arc::new(factory))
    .with_tool_call_retries();

pub fn with_filter<F>(self, filter: F) -> McpToolset<S>

where F: Fn(&str) -> bool + Send + Sync + 'static,

Add a filter to select which tools to expose.

The filter function receives a tool name and returns true if the tool should be included.

Example

let toolset = McpToolset::new(client)
    .with_filter(|name| {
        matches!(name, "read_file" | "list_directory" | "search_files")
    });

pub fn with_tools(self, tool_names: &[&str]) -> McpToolset<S>

Add a filter that only includes tools with the specified names.

Example

let toolset = McpToolset::new(client)
    .with_tools(&["read_file", "write_file"]);

pub async fn cancellation_token(&self) -> RunningServiceCancellationToken

Get a cancellation token that can be used to shutdown the MCP server.

Call cancel() on the returned token to cleanly shutdown the MCP server. This should be called before exiting to avoid EPIPE errors.

Example

let toolset = McpToolset::new(client);
let cancel_token = toolset.cancellation_token().await;

// ... use the toolset ...

// Before exiting:
cancel_token.cancel();

pub async fn is_closed(&self) -> bool

Check whether the underlying MCP service connection has been closed or cancelled.

Returns true if the service loop has terminated (transport closed, cancellation token fired, or the background task completed). This is useful for health monitoring — a closed connection indicates the server process has crashed or the transport has been lost.

Example

if toolset.is_closed().await {
    tracing::warn!("MCP server connection lost");
}

pub async fn call_tool_value( &self, name: &str, arguments: Map<String, Value>, ) -> Result<Value, AdkError>

Call one MCP tool and preserve structured, text, image, audio, and resource content in the same ADK multimodal value shape used by model-facing tool execution.

pub async fn list_resources(&self) -> Result<Vec<Resource>, AdkError>

List static resources from the connected MCP server.

Returns the list of resources advertised by the server via the resources/list protocol method. Returns an empty Vec when the server does not support resources (i.e. responds with MethodNotFound).

Errors

Returns AdkError::Tool on transport or unexpected server errors.

pub async fn list_resource_templates( &self, ) -> Result<Vec<ResourceTemplate>, AdkError>

List URI template resources from the connected MCP server.

Returns the list of resource templates advertised by the server via the resourceTemplates/list protocol method. Returns an empty Vec when the server does not support resource templates (i.e. responds with MethodNotFound).

Errors

Returns AdkError::Tool on transport or unexpected server errors.

pub async fn read_resource( &self, uri: &str, ) -> Result<Vec<ResourceContents>, AdkError>

Read a resource by URI from the connected MCP server.

Delegates to the resources/read protocol method. Returns the resource contents on success.

Errors

Returns AdkError::Tool("resource not found: {uri}") when the URI does not match any resource on the server. Returns a generic AdkError::Tool on transport or other server errors.

pub async fn list_prompts(&self) -> Result<Vec<Prompt>, AdkError>

Return the prompt templates published by the connected MCP server.

pub async fn get_prompt( &self, name: &str, arguments: Option<Map<String, Value>>, ) -> Result<GetPromptResult, AdkError>

Resolve one published MCP prompt with optional typed arguments.

pub async fn complete_prompt_argument( &self, prompt_name: &str, argument_name: &str, current_value: &str, context: Option<CompletionContext>, ) -> Result<CompletionInfo, AdkError>

Request completion suggestions for one prompt argument.

pub async fn complete_resource_argument( &self, uri_template: &str, argument_name: &str, current_value: &str, context: Option<CompletionContext>, ) -> Result<CompletionInfo, AdkError>

Request completion suggestions for one resource-template argument.

pub async fn subscribe_resource(&self, uri: &str) -> Result<(), AdkError>

Subscribe to change notifications for a resource URI.

pub async fn unsubscribe_resource(&self, uri: &str) -> Result<(), AdkError>

Remove a resource subscription created by subscribe_resource.

impl McpToolset<AdkClientHandler>

pub async fn with_elicitation_handler<T, E, A>( transport: T, handler: Arc<dyn ElicitationHandler>, ) -> Result<McpToolset<AdkClientHandler>, AdkError>

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

Create a McpToolset with elicitation support from a transport.

This creates the MCP client using AdkClientHandler, which advertises elicitation capabilities and delegates requests to the provided handler.

Example

use adk_tool::{McpToolset, ElicitationHandler, AutoDeclineElicitationHandler};
use adk_tool::mcp::rmcp::transport::TokioChildProcess;
use tokio::process::Command;
use std::sync::Arc;

let transport = TokioChildProcess::new(Command::new("my-mcp-server"))?;
let handler = Arc::new(AutoDeclineElicitationHandler);
let toolset = McpToolset::with_elicitation_handler(transport, handler).await?;

ConnectionFactory with Elicitation

To preserve elicitation across reconnections, clone the Arc<dyn ElicitationHandler> into your ConnectionFactory implementation:

use adk_tool::{McpToolset, ElicitationHandler};
use adk_tool::mcp::ConnectionFactory;
use adk_tool::mcp::rmcp::{
    ServiceExt,
    service::{RoleClient, RunningService},
    transport::TokioChildProcess,
};
use tokio::process::Command;
use std::sync::Arc;

struct MyReconnectFactory {
    handler: Arc<dyn ElicitationHandler>,
    server_command: String,
}

// The factory creates a fresh AdkClientHandler on each reconnection,
// so the new connection advertises elicitation capabilities.
// The ConnectionFactory trait itself is unchanged.

pub async fn with_handlers<T, E, A>( transport: T, elicitation_handler: Arc<dyn ElicitationHandler>, resource_notification_handler: Arc<dyn ResourceNotificationHandler>, ) -> Result<McpToolset<AdkClientHandler>, AdkError>

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

Create an MCP toolset with elicitation and resource notification handlers.

Both handlers are installed before the protocol handshake, so resource update notifications can be received immediately after subscribing.

Trait Implementations

impl<S> Clone for McpToolset<S>

where S: Service<RoleClient> + Send + Sync + 'static,

fn clone(&self) -> McpToolset<S>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<S> Toolset for McpToolset<S>

where S: Service<RoleClient> + Send + Sync + 'static,

fn name(&self) -> &str

Returns the name of this toolset.

fn tools<'life0, 'async_trait>( &'life0 self, _ctx: Arc<dyn ReadonlyContext>, ) -> Pin<Box<dyn Future<Output = Result<Vec<Arc<dyn Tool>>, AdkError>> + Send + 'async_trait>>

where 'life0: 'async_trait, McpToolset<S>: 'async_trait,

Returns the tools available in this toolset for the given context.