Skip to content

Pool ​

Category: Mcp_client

Source: pool.dart

[McpClientPool] — one [McpClient] per configured MCP server.

The pool owns the lifecycle (connect / reconnect / disconnect / shutdown), exposes the union of advertised tools to the agent, and emits an [McpPoolEvent] stream that App consumes for status messages and the status bar.

Why [McpPoolEvent] and not [McpServerConnectedEvent] etc. directly: SessionEvent requires a turnId + monotonic sequence, which is the session bus's job. The pool is below the session bus. When the bus is wired (per docs/plans/2026-04-29-harness-layers.md), a thin adapter will translate pool events into the typed SessionEvent variants. Until then, App reads pool events directly.

Classes ​

sealed McpPoolEvent ​

Constructor ​

dart
const McpPoolEvent({required this.serverId})

Properties ​

PropertyTypeDescription
serverIdString

McpPoolServerConnectedEvent ​

Constructor ​

dart
const McpPoolServerConnectedEvent({
    required super.serverId,
    required this.serverName,
    required this.serverVersion,
    required this.toolNames,
  })

Properties ​

PropertyTypeDescription
serverNameString
serverVersionString
toolNamesList<String>Namespaced (<serverId>.<tool>).

McpPoolServerDisconnectedEvent ​

Constructor ​

dart
const McpPoolServerDisconnectedEvent({
    required super.serverId,
    required this.reason,
    this.reconnectAttempt = 0,
    this.nextAttemptIn = Duration.zero,
  })

Properties ​

PropertyTypeDescription
reasonMcpDisconnectReason
reconnectAttemptint
nextAttemptInDuration

McpPoolServerErrorEvent ​

Constructor ​

dart
const McpPoolServerErrorEvent({
    required super.serverId,
    required this.kind,
    required this.message,
  })

Properties ​

PropertyTypeDescription
kindMcpServerErrorKind
messageString

McpPoolServerAuthRequiredEvent ​

Constructor ​

dart
const McpPoolServerAuthRequiredEvent({
    required super.serverId,
    required this.reauthCommand,
    this.resourceMetadataUrl,
    this.wwwAuthenticate,
  })

Properties ​

PropertyTypeDescription
reauthCommandString
resourceMetadataUrlUri?resource_metadata URL from the server's WWW-Authenticate header, if any. Surfaces this back into [McpAuthFlowRunner.cachedResourceMetadataUrl] so the panel doesn't re-probe.
wwwAuthenticateString?Raw WWW-Authenticate header. Used by the auth flow to feed discoverMcpAuth directly.

McpPoolToolListChangedEvent ​

Constructor ​

dart
const McpPoolToolListChangedEvent({
    required super.serverId,
    required this.added,
    required this.removed,
  })

Properties ​

PropertyTypeDescription
addedList<String>
removedList<String>

McpServerSnapshot ​

Constructor ​

dart
McpServerSnapshot({
    required this.spec,
    required this.state,
    this.tools = const [],
    this.lastError,
  })

Properties ​

PropertyTypeDescription
specMcpServerSpec
stateMcpConnectionState
toolsList<McpTool>
lastErrorString?
idString get
enabledbool get
toolCountint get
idString get
enabledbool get
toolCountint get

McpClientPool ​

Constructor ​

dart
McpClientPool({
    required this.config,
    required this.credentials,
    Set<String>? reservedToolNames,
    McpClientFactory? clientFactory,
    McpRefreshGrant? refreshGrant,
  })

Properties ​

PropertyTypeDescription
configMcpConfig
credentialsCredentialStore
eventsStream&lt;McpPoolEvent&gt; get
serversIterable&lt;McpServerSnapshot&gt; getAll server snapshots, in YAML order.
allToolsIterable&lt;McpTool&gt; getAll tools advertised by all currently-connected servers. Namespaced names; safe to add directly to an agent's tool registry.
eventsStream&lt;McpPoolEvent&gt; get
serversIterable&lt;McpServerSnapshot&gt; getAll server snapshots, in YAML order.
allToolsIterable&lt;McpTool&gt; getAll tools advertised by all currently-connected servers. Namespaced names; safe to add directly to an agent's tool registry.
unhealthyCountint getCount of servers in reconnecting, dead, or awaiting auth state. Drives the status-bar "MCP: N unhealthy" badge.
awaitingAuthCountint getNumber of servers in [McpAwaitingAuth] specifically — drives the MCP: 1 needs auth status-bar label when the unhealthy set is auth-only.

Methods ​

McpServerSnapshot? server(String id) ​

Look up a server by id (the YAML key).

void connectAll() ​

Fire connect() for every enabled server in parallel; don't await. Each server's tools become available as its handshake completes. Servers that fail are surfaced via [events] and left in a state the user can inspect via glue mcp list / /mcp list.

Future&lt;void&gt; reconnect(String serverId) ​

Reconnect a specific server. Clears dead state if applicable and cancels any pending automatic-retry timer so the manual action takes precedence.

Future&lt;void&gt; toggle(String serverId) ​

Session-scoped enable/disable. Doesn't write back to config.

Future&lt;void&gt; close() ​

Functions ​

`Future<McpClient> defaultMcpClientFactory( ​

McpServerSpec spec, CredentialStore credentials, { int defaultCallTimeoutSeconds = 30, })`

Default factory — spawns real transports for each spec type.

The per-call timeout resolves to the server's own [McpServerSpec.callTimeoutSeconds] when set, otherwise [defaultCallTimeoutSeconds] (the pool passes [McpConfig.callTimeoutSeconds]) — without this the config value was parsed but never applied and the client's built-in 30s default always won (M1).

Released under the MIT License.