Struct McpClientPool 

pub struct McpClientPool { /* private fields */ }

Centralized MCP client lifecycle manager.

Provides lazy connection establishment, per-server deduplication, and coordinated shutdown of all MCP server processes.

Clone semantics

Cloning is cheap (Arc inner). All clones share the same pool state. This enables sharing across TaskExecutor, TUI App, and ChatAgent.

Example

let pool = McpClientPool::with_configs(event_log, mcp_configs);

// Lazy connect (first call spawns server, subsequent return cached)
let client = pool.get_or_connect("neo4j").await?;
client.call_tool("novanet_search", params).await?;

// Graceful shutdown (disconnects all servers)
pool.shutdown_all().await;

Implementations

impl McpClientPool

pub fn new(event_log: EventLog) -> McpClientPool

Create an empty pool (no server configurations loaded yet).

pub fn with_configs( event_log: EventLog, configs: HashMap<String, McpConfigInline, FxBuildHasher>, ) -> McpClientPool

Create a pool with pre-loaded server configurations.

pub fn set_configs( &self, configs: HashMap<String, McpConfigInline, FxBuildHasher>, )

Replace all server configurations.

Does NOT disconnect existing clients. Call shutdown_all() first if you need to force reconnection with new configs.

pub fn configs( &self, ) -> RwLockReadGuard<'_, RawRwLock, HashMap<String, McpConfigInline, FxBuildHasher>>

Get a read reference to the current configs.

pub fn has_config(&self, name: &str) -> bool

Check if a configuration exists for the given server name.

pub fn config_count(&self) -> usize

Return the number of configured MCP servers.

pub fn event_log(&self) -> &EventLog

Get the event log.

pub async fn get_or_connect( &self, name: &str, ) -> Result<Arc<McpClient>, McpError>

Get an existing client or establish a new connection.

This is the primary API. It:

1. Returns a cached client if already connected
2. Spawns the server process and connects if this is the first call
3. Serializes concurrent init attempts per server (OnceCell)
4. Retries automatically if a previous init attempt failed

Errors

• McpError::McpNotConfigured if no config exists for this server
• McpError::McpStartError if the server process fails to spawn
• McpError::McpStartError if the pool is shut down

pub fn is_connected(&self, name: &str) -> bool

Check if a server has an active (initialized) connection.

pub fn connected_count(&self) -> usize

Count of servers with active connections.

pub fn is_shutdown(&self) -> bool

Check if the pool has been shut down.

pub async fn disconnect(&self, name: &str) -> Result<(), McpError>

Disconnect a specific server and remove it from the pool.

Always removes the entry to prevent dangling OnceCell references, even if disconnect fails. The next call to get_or_connect() will re-initialize.

pub async fn shutdown_all(&self)

Gracefully shut down all MCP server connections.

After this call:

• All server processes are terminated
• The pool is marked as shut down
• get_or_connect() will return Err for all subsequent calls

This method is idempotent.

pub fn inject_mock(&self, name: &str, client: Arc<McpClient>)

Inject a pre-built client for testing.

The client is inserted as already-initialized, bypassing connect_server(). Only intended for test code (production callers use connect_server).

Trait Implementations

impl Clone for McpClientPool

fn clone(&self) -> McpClientPool

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for McpClientPool

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

Formats the value using the given formatter.