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

const McpPoolEvent({required this.serverId})

Properties

Property	Type	Description
serverId	String

McpPoolServerConnectedEvent

Constructor

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

Properties

Property	Type	Description
serverName	String
serverVersion	String
toolNames	List<String>	Namespaced (<serverId>.<tool>).

McpPoolServerDisconnectedEvent

Constructor

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

Properties

Property	Type	Description
reason	McpDisconnectReason
reconnectAttempt	int
nextAttemptIn	Duration

McpPoolServerErrorEvent

Constructor

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

Properties

Property	Type	Description
kind	McpServerErrorKind
message	String

McpPoolServerAuthRequiredEvent

Constructor

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

Properties

Property	Type	Description
reauthCommand	String
resourceMetadataUrl	Uri?	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.
wwwAuthenticate	String?	Raw WWW-Authenticate header. Used by the auth flow to feed discoverMcpAuth directly.

McpPoolToolListChangedEvent

Constructor

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

Properties

Property	Type	Description
added	List<String>
removed	List<String>

McpServerSnapshot

Constructor

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

Properties

Property	Type	Description
spec	McpServerSpec
state	McpConnectionState
tools	List<McpTool>
lastError	String?
id	String get
enabled	bool get
toolCount	int get
id	String get
enabled	bool get
toolCount	int get

McpClientPool

Constructor

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

Properties

Property	Type	Description
config	McpConfig
credentials	CredentialStore
events	Stream<McpPoolEvent> get
servers	Iterable<McpServerSnapshot> get	All server snapshots, in YAML order.
allTools	Iterable<McpTool> get	All tools advertised by all currently-connected servers. Namespaced names; safe to add directly to an agent's tool registry.
events	Stream<McpPoolEvent> get
servers	Iterable<McpServerSnapshot> get	All server snapshots, in YAML order.
allTools	Iterable<McpTool> get	All tools advertised by all currently-connected servers. Namespaced names; safe to add directly to an agent's tool registry.
unhealthyCount	int get	Count of servers in reconnecting, dead, or awaiting auth state. Drives the status-bar "MCP: N unhealthy" badge.
awaitingAuthCount	int get	Number 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<void> 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<void> toggle(String serverId)

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

Future<void> close()

Functions

`Future<McpClient> defaultMcpClientFactory(

McpServerSpec spec, CredentialStore credentials, )`

Default factory — spawns real transports for each spec type.