Client class

Main MCP Client class that handles all client-side protocol operations

Available extensions

Constructors

Client({required String name, required String version, String? description, ClientCapabilities capabilities = const ClientCapabilities()})
Creates a new MCP client with the specified parameters

Properties

capabilities → ClientCapabilities
Client capabilities configuration
final
description → String?
Spec 2025-11-25+: optional human-readable description of this client implementation. Emitted on clientInfo during initialize when set; older peers ignore it (additive).
final
hashCode → int
The hash code for this object.
no setterinherited
isConnected → bool
Whether the client is currently connected
no setter
isStateless → bool
Whether this client is operating in the 2026-07-28 stateless mode.
no setter
name → String
Name of the MCP client
final
negotiatedProtocolVersion → String?
Negotiated protocol revision after initialize completes; null before then.
no setter
onConnect → Stream<ServerInfo>
Stream of connection events
no setter
onDisconnect → Stream<DisconnectReason>
Stream of disconnection events
no setter
onError → Stream<McpError>
Stream of error events
no setter
protocolVersion → String
Protocol version this client implements
final
roots → List<Root>
Locally configured roots (URI / filesystem boundaries the server is allowed to operate in). Mutations push notifications/roots/list_changed to the server.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
serverCapabilities → ServerCapabilities?
Get the server capabilities
no setter
serverInfo → Map<String, dynamic>?
Get the server information
no setter
supportsTasks → bool
Whether the server advertised the tasks extension (from the last initialize/discover). Task calls only make sense when true.
no setter
version → String
Version of the MCP client implementation
final

Methods

addRoot(Root root) → void
Add a root to the client's local list. Server is notified via notifications/roots/list_changed.
addRootMap(Map<String, dynamic> root) → void
Map-based variant of addRoot for callers that don't have the typed Root available. Constructs a Root from the supplied map (must contain at least uri) and delegates to addRoot.
callTool(String name, Map<String, dynamic> toolArguments) → Future<CallToolResult>
Call a tool on the server
callToolWithTracking(String name, Map<String, dynamic> arguments, {bool trackProgress = true}) → Future<ToolCallTracking>
Call a tool and get the operation ID for tracking progress
cancelTask(String taskId) → Future<void>
Cancel a task (tasks/cancel, cooperative + eventually consistent).
connect(ClientTransport transport, {bool statelessMode = false}) → Future<void>
Connect the client to a transport.
connectWithRetry(ClientTransport transport, {int maxRetries = 3, Duration delay = const Duration(seconds: 2)}) → Future<void>
Connect with retry mechanism
disconnect() → void
Disconnect the client from its transport
discover() → Future<DiscoverResult>
2026-07-28 stateless core: fetch the server's supported versions, capabilities, and optional instructions via server/discover.
dispose() → void
Dispose client resources
getPrompt(String name, [Map<String, dynamic>? promptArguments]) → Future<GetPromptResult>
Get a prompt from the server
getResourceWithTemplate(String templateUri, Map<String, dynamic> params) → Future<ReadResourceResult>
Get a resource using a template
getTask(String taskId) → Future<Task>
Poll a task's current state (tasks/get).
initialize() → Future<void>
Initialize the connection to the server
listen(SubscriptionFilter filter) → Future<Subscription>
Open a 2026-07-28 subscriptions/listen stream (SEP-2577) — the stateless replacement for the resources/subscribe RPC + the HTTP GET SSE stream.
listPrompts() → Future<List<Prompt>>
List available prompts on the server
listResources() → Future<List<Resource>>
List available resources on the server
listResourceTemplates() → Future<List<ResourceTemplate>>
List resource templates on the server
listTools() → Future<List<Tool>>
List available tools on the server
listToolsMetadata(ToolRegistry registry) → Future<List<ToolMetadata>>

Available on Client, provided by the ClientToolMetadataExtension extension

Fetch tools and return metadata only Caches full tools in provided registry for later schema lookup
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
notifyCancelled(String requestId, {String? reason}) → void
Cancel an in-flight server-side operation.
notifyProgress(dynamic progressToken, double progress, {double? total, String? message}) → void
Report progress on an in-flight server-initiated request (spec notifications/progress). progressToken is the token the server sent in the original request's _meta.progressToken.
onElicitationRequest(Future<Map<String, dynamic>> handler(Map<String, dynamic> params)) → void
Register a handler for server-initiated elicitation/create requests (spec 2025-06-18). The handler shows the requested form to the user and returns { action, content? } per spec — action is accept / decline / cancel.
onElicitationRequestTyped(Future<ElicitationResponse> handler(ElicitationRequest request)) → void
Typed variant of onElicitationRequest (spec 2025-11-25). The handler receives a parsed ElicitationRequest — form fields typed as ElicitationFieldSchema (strings/numbers/booleans with defaults, single- and multi-select enums with enumNames), or a URL-mode request (mode: "url") — and returns a typed ElicitationResponse.
onListRoots(Future<List<Root>> handler()) → void
Register a custom handler for server-initiated roots/list requests. By default the client responds with the locally configured roots list — supply this to override.
onListRootsMap(Future<List<Map<String, dynamic>>> handler()) → void
Map-based variant of onListRoots. The handler returns the raw list of root maps (each with at least a uri key); this method wraps it in the spec response shape. Sibling to onSamplingRequestMap — same rationale.
onLogging(dynamic handler(McpLogLevel, String, String?, Map<String, dynamic>?)) → void
Handle logging notification
onNotification(String method, dynamic handler(Map<String, dynamic>)) → void
Register a notification handler
onProgress(dynamic handler(String requestId, double progress, String message)) → void
Register a handler for progress updates from the server
onPromptsListChanged(dynamic handler()) → void
Handle prompts list changed notification
onResourceContentUpdated(dynamic handler(String uri, ResourceContentInfo content)) → void
Register a handler for resource update notifications with content
onResourcesListChanged(dynamic handler()) → void
Handle resources list changed notification
onResourceUpdated(dynamic handler(String)) → void
Handle resource updated notification
onRootsListChanged(dynamic handler()) → void
Handle roots list changed notification
onSamplingRequest(Future<CreateMessageResult> handler(CreateMessageRequest request)) → void
Register a handler for server-initiated sampling/createMessage requests. The driver app (Claude Desktop / Claude Code / a vibe-style IDE) fulfils the prompt with its own LLM and returns the spec CreateMessageResult (role, content, model, optional stopReason).
onSamplingRequestMap(Future<Map<String, dynamic>> handler(Map<String, dynamic> params)) → void
Map-based variant of onSamplingRequest. Receives the spec CreateMessageRequest.params as a raw map and must return the raw CreateMessageResult map.
onToolsListChanged(dynamic handler()) → void
Handle tools list changed notification
readResource(String uri) → Future<ReadResourceResult>
Read a resource from the server
removeRoot(String uri) → void
Remove a root from the client's local list. Server is notified via notifications/roots/list_changed.
setLoggingLevel(McpLogLevel level) → Future<void>
Set the logging level for the server
subscribeResource(String uri) → Future<void>
Subscribe to a resource
taskFromResult(Map<String, dynamic> result) → Task?
If a tools/call (or other) result is a CreateTaskResult (resultType: "task"), returns the Task handle; otherwise null.
toString() → String
A string representation of this object.
inherited
unsubscribeResource(String uri) → Future<void>
Unsubscribe from a resource
updateTask(String taskId, Map<String, dynamic> inputResponses) → Future<void>
Deliver input responses to an input_required task (tasks/update). inputResponses is keyed by the task's outstanding inputRequests keys.

Operators

operator ==(Object other) → bool
The equality operator.
inherited