Struct McpServerManager 

pub struct McpServerManager { /* private fields */ }

Available on crate feature tools only.

Manages the full lifecycle of multiple local MCP server child processes.

McpServerManager spawns processes, connects them via TokioChildProcess transport into McpToolset instances, monitors health, auto-restarts on crash with exponential backoff, and aggregates tools from all managed servers behind the Toolset trait.

Construction

Use McpServerManager::new with a map of server configurations, then chain builder methods to configure handlers and intervals:

use adk_tool::mcp::manager::{McpServerConfig, McpServerManager};
use std::collections::HashMap;
use std::time::Duration;

let configs = HashMap::from([
    ("my-server".to_string(), McpServerConfig {
        command: "/opt/company/bin/workspace-mcp".to_string(),
        args: vec!["--stdio".to_string(), "--root".to_string(), "/srv/workspace".to_string()],
        ..Default::default()
    }),
]);

let manager = McpServerManager::new(configs)
    .with_health_check_interval(Duration::from_secs(15))
    .with_grace_period(Duration::from_secs(3))
    .with_name("my_manager");

Implementations

impl McpServerManager

pub fn new(configs: HashMap<String, McpServerConfig>) -> McpServerManager

Available on crate feature mcp only.

Create a new McpServerManager from a map of server configurations.

Each entry is keyed by a unique server ID. Servers with disabled: true are initialized with ServerStatus::Disabled; all others start as ServerStatus::Stopped.

No servers are started automatically — call start_server or start_all to begin spawning processes.

pub fn from_json(json: &str) -> Result<McpServerManager, AdkError>

Available on crate feature mcp only.

Create a new McpServerManager by parsing a JSON string in Kiro mcp.json format.

The JSON must contain a top-level mcpServers object mapping server IDs to their configurations. CamelCase JSON field names are automatically mapped to snake_case Rust fields.

Errors

Returns AdkError::Tool if the JSON is malformed or missing required fields.

Example

let json = r#"{
    "mcpServers": {
        "workspace": {
            "command": "/opt/company/bin/workspace-mcp",
            "args": ["--stdio", "--root", "/srv/workspace"]
        }
    }
}"#;
let manager = McpServerManager::from_json(json)?;

pub fn from_json_file( path: impl AsRef<Path>, ) -> Result<McpServerManager, AdkError>

Available on crate feature mcp only.

Create a new McpServerManager by reading and parsing a JSON file from disk.

The file must contain JSON in Kiro mcp.json format (see from_json). File reading is synchronous, which is acceptable for config loading at startup.

Errors

Returns AdkError::Tool if the file cannot be read or the JSON is malformed.

Example

let manager = McpServerManager::from_json_file("mcp.json")?;

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

Available on crate feature mcp only.

Set the elicitation handler used for all managed server connections.

The handler is preserved across server restarts via Arc sharing.

pub fn with_resource_notification_handler( self, handler: Arc<dyn ResourceNotificationHandler>, ) -> McpServerManager

Available on crate feature mcp only.

Set the resource notification handler used for all managed connections.

The handler is retained across manual and automatic server restarts.

pub fn with_health_check_interval(self, interval: Duration) -> McpServerManager

Available on crate feature mcp only.

Set the interval between health check cycles.

Default: 30 seconds.

pub fn with_grace_period(self, period: Duration) -> McpServerManager

Available on crate feature mcp only.

Set the grace period reserved for managed-session shutdown.

Default: 5 seconds.

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

Available on crate feature mcp only.

Set the name returned by the Toolset::name() implementation.

Default: "mcp_server_manager".

pub async fn start_server(&self, id: &str) -> Result<(), AdkError>

Available on crate feature mcp only.

Start a managed MCP server by ID.

Spawns the configured command as a child process, creates a TokioChildProcess transport, and connects via McpToolset with the configured elicitation (and optionally sampling) handler.

If the server is already Running, this is a no-op and returns Ok(()).

Errors

Returns AdkError::Tool if:

• The server ID does not exist
• The child process fails to spawn
• The MCP handshake fails

Example

manager.start_server("my-server").await?;

pub async fn stop_server(&self, id: &str) -> Result<(), AdkError>

Available on crate feature mcp only.

Stop a managed MCP server by ID.

Cancels the MCP session via the toolset’s cancellation token, drops the McpToolset connection, and sets the status to Stopped.

If the server is not running, this is a no-op and returns Ok(()).

Errors

Returns AdkError::Tool if the server ID does not exist.

Example

manager.stop_server("my-server").await?;

pub async fn restart_server(&self, id: &str) -> Result<(), AdkError>

Available on crate feature mcp only.

Restart a managed MCP server by ID.

Sets the status to Restarting, stops the server, then starts it again. The same ElicitationHandler and SamplingHandler Arcs are preserved across the restart.

Errors

Returns AdkError::Tool if:

• The server ID does not exist
• The start phase fails (status set to FailedToStart)

Example

manager.restart_server("my-server").await?;

pub async fn server_status(&self, id: &str) -> Result<ServerStatus, AdkError>

Available on crate feature mcp only.

Return the current ServerStatus for a given server ID.

Errors

Returns AdkError::Tool if the server ID does not exist.

Example

let status = manager.server_status("my-server").await?;
assert_eq!(status, ServerStatus::Running);

pub async fn list_server_resources( &self, id: &str, ) -> Result<Vec<Resource>, AdkError>

Available on crate feature mcp only.

List static resources published by one running managed server.

pub async fn list_server_resource_templates( &self, id: &str, ) -> Result<Vec<ResourceTemplate>, AdkError>

Available on crate feature mcp only.

List URI templates published by one running managed server.

pub async fn list_server_prompts( &self, id: &str, ) -> Result<Vec<Prompt>, AdkError>

Available on crate feature mcp only.

List prompt templates published by one running managed server.

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

Available on crate feature mcp only.

Read one resource from a running managed server.

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

Available on crate feature mcp only.

Subscribe to updates for one resource on a running managed server.

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

Available on crate feature mcp only.

Remove a resource subscription from one running managed server.

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

Available on crate feature mcp only.

Resolve one prompt from a running managed server.

pub async fn all_statuses(&self) -> HashMap<String, ServerStatus>

Available on crate feature mcp only.

Return a map of all server IDs to their current ServerStatus.

Example

let statuses = manager.all_statuses().await;
for (id, status) in &statuses {
    println!("{id}: {status:?}");
}

pub async fn running_server_count(&self) -> usize

Available on crate feature mcp only.

Return the number of servers currently in ServerStatus::Running status.

Example

let count = manager.running_server_count().await;
println!("{count} servers running");

pub fn start_monitoring(&self)

Available on crate feature mcp only.

Start the background health monitoring task.

Spawns a tokio::spawn task that periodically checks each Running server by calling McpToolset::is_closed(). If a server’s connection is closed, the monitor sets its status to Crashed and, if a RestartPolicy is configured, attempts auto-restart with exponential backoff.

The monitoring loop runs until stop_monitoring is called, which cancels the background task via the internal CancellationToken.

Example

manager.start_monitoring();
// ... later ...
manager.stop_monitoring();

pub fn stop_monitoring(&self)

Available on crate feature mcp only.

Stop the background health monitoring task.

Cancels the monitoring loop spawned by start_monitoring. This is a no-op if monitoring was never started or has already been stopped.

Example

manager.stop_monitoring();

pub async fn add_server( &self, id: String, config: McpServerConfig, ) -> Result<(), AdkError>

Available on crate feature mcp only.

Register a new server configuration at runtime.

The new server is initialized with ServerStatus::Disabled if config.disabled is true, or ServerStatus::Stopped otherwise. It will not be started automatically — call start_server to begin spawning the process.

Errors

Returns AdkError::Tool if a server with the given ID already exists.

Example

let config = McpServerConfig {
    command: "/opt/company/bin/billing-mcp".to_string(),
    args: vec!["--stdio".to_string()],
    ..Default::default()
};
manager.add_server("new-server".to_string(), config).await?;

pub async fn server_config(&self, id: &str) -> Result<McpServerConfig, AdkError>

Available on crate feature mcp only.

Return a copy of one server’s current configuration.

pub async fn all_configs(&self) -> HashMap<String, McpServerConfig>

Available on crate feature mcp only.

Return a snapshot of every managed server configuration.

pub async fn update_server( &self, id: &str, config: McpServerConfig, ) -> Result<(), AdkError>

Available on crate feature mcp only.

Replace a server configuration at runtime.

A running server is stopped and restarted with the new configuration. If the replacement fails to start, the previous configuration is restored and restarted before the error is returned.

pub async fn enable_server(&self, id: &str) -> Result<(), AdkError>

Available on crate feature mcp only.

Enable a disabled server without starting it.

pub async fn disable_server(&self, id: &str) -> Result<(), AdkError>

Available on crate feature mcp only.

Stop and disable a server until it is explicitly enabled again.

pub async fn to_json(&self) -> Result<String, AdkError>

Available on crate feature mcp only.

Serialize the current in-memory configuration as compatible mcp.json.

pub async fn save_json_file( &self, path: impl AsRef<Path>, ) -> Result<(), AdkError>

Available on crate feature mcp only.

Persist the current configuration using an atomic temporary-file rename.

pub async fn remove_server(&self, id: &str) -> Result<(), AdkError>

Available on crate feature mcp only.

Remove a server configuration at runtime.

If the server is currently running, it is stopped first using the graceful stop sequence before being removed from the manager.

Errors

Returns AdkError::Tool if the server ID does not exist.

Example

manager.remove_server("old-server").await?;

pub async fn start_all(&self) -> HashMap<String, Result<(), AdkError>>

Available on crate feature mcp only.

Start all non-disabled servers and report each result independently.

Collects all server IDs where disabled == false, then starts each one via start_server. Failures are logged but do not prevent other servers from starting. Registry mutations are serialized while each child process completes its MCP handshake.

Returns

A HashMap<String, Result<()>> with per-server outcomes. Disabled servers are not included in the result.

Example

let results = manager.start_all().await;
for (id, result) in &results {
    match result {
        Ok(()) => println!("{id}: started"),
        Err(e) => eprintln!("{id}: failed to start: {e}"),
    }
}

pub async fn shutdown(&self) -> Result<(), AdkError>

Available on crate feature mcp only.

Shut down all managed servers and stop health monitoring.

This method first stops the health monitoring task, then stops all running servers by cancelling their MCP sessions and dropping the child transports. After shutdown, all server statuses are set to Stopped.

Example

manager.shutdown().await?;
// All servers are now stopped, safe to drop the manager

Trait Implementations

impl Drop for McpServerManager

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl Toolset for McpServerManager

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, McpServerManager: 'async_trait,

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