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.

MRTR and in-task input requests follow ADK’s input policy when the client runs on AdkClientHandler, which rejects sampling and roots. Any other handler receives elicitation requests, and sampling or roots requests only when it declared those capabilities.

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_schema_limits(self, limits: McpSchemaLimits) -> McpToolset<S>

Set the size limits checked against each discovered tool schema.

Discovery measures every input and output schema before copying or logging it. A tool whose schema exceeds a limit is skipped with a warning naming this toolset and the tool, and the remaining tools are still registered. See McpSchemaLimits for how size is measured and why the defaults are what they are.

Example

use adk_tool::mcp::{McpSchemaLimits, McpToolset};

fn admit_larger_schemas(toolset: McpToolset) -> McpToolset {
    toolset.with_schema_limits(
        McpSchemaLimits::default().with_max_bytes(1024 * 1024).with_max_nodes(40_000),
    )
}

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 cancel_pending_tasks(&self) -> Result<(), AdkError>

Cancels every remote task this toolset started and has not seen finish.

The set covers tasks whose tool-call future was dropped and tasks an in-flight call is still polling, so this also cancels in-flight calls: each one returns a task error once the server reports the cancellation.

Each task is checked with tasks/get first. A task that is already terminal, or that the server no longer knows (its TTL expired, or the connection was refreshed into a new session), is released without a cancel request. Any other task receives tasks/cancel and a second tasks/get. A task stays tracked until a terminal status or an unknown-task response confirms it, so calling this again re-checks it.

Nothing else prunes the set: every task whose call ended before it saw a terminal status stays tracked until this runs, so a long-lived toolset that drops calls should call it periodically as well as at shutdown.

Cancellation is cooperative on the server side, so bound this call with the shutdown deadline. McpServerManager runs it within its grace period before closing a managed session.

Errors

Returns AdkError::Tool naming a task whose outcome is not confirmed: tasks/get or tasks/cancel failed for a reason other than an unknown or finished task, or the task is still running after the cancel request. Tasks confirmed by the same call are released regardless.

Example

use adk_tool::mcp::McpToolset;
use std::time::Duration;

async fn shutdown(toolset: &McpToolset) {
    let cleanup = toolset.cancel_pending_tasks();
    match tokio::time::timeout(Duration::from_secs(5), cleanup).await {
        Ok(Ok(())) => {}
        Ok(Err(error)) => tracing::warn!(%error, "remote MCP tasks may still run"),
        Err(_) => tracing::warn!("MCP task cleanup exceeded the shutdown deadline"),
    }
    toolset.cancellation_token().await.cancel();
}

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.

fn process_llm_request<'life0, 'life1, 'async_trait>( &'life0 self, _ctx: Arc<dyn ReadonlyContext>, _request: &'life1 mut LlmRequest, ) -> Pin<Box<dyn Future<Output = Result<(), AdkError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, Self: 'async_trait,

Applies toolset-specific context to an LLM request before each model call.