leehack/mcp_dart/mcp-dart-client

Building an MCP client with mcp_dart

McpClient connects to one MCP server through a transport. By default it tries MCP 2026-07-28 discovery and falls back to initialization-era versions (MCP 2025-11-25 and earlier) for legacy servers, so it works with Dart, TypeScript and Python servers alike. Import everything from package:mcp_dart/mcp_dart.dart.

Guidelines

• Create one McpClient per server connection and always

await client.close() in a finally block or when the owning object is disposed. close() also stops a spawned stdio process.

• Pick the transport by where the server runs:
• Local helper process (Dart VM, desktop): `StdioClientTransport(

StdioServerParameters(command: ..., args: [...]))`.

• Remote service, browser, Flutter Web or mobile: `StreamableHttpClientTransport(

Uri.parse('https://host/mcp'))`. Browsers and mobile apps cannot spawn stdio servers.

• SseClientTransport is deprecated legacy HTTP+SSE; use it only for old

servers that lack Streamable HTTP.

• Keep the default McpProtocol.stable profile. Pass

McpClientOptions(protocol: McpProtocol.legacy) or McpProtocol.require2026 only to pin an era. The era is fixed per connection; open a new connection to change it.

• Stdio child processes inherit the parent environment by default. To keep

host secrets from a third-party server, pass a sanitized environment and includeParentEnvironment: false.

• After connect, check client.getServerCapabilities() before optional

operations (resources, prompts, completions, legacy resources.subscribe). An SDK method existing does not mean the server supports it.

• Treat listTools() results as the source of truth for tool names and input

schemas. List methods are paginated: pass nextCursor back unchanged until it is null, and stop if a cursor repeats.

• callTool returns CallToolResult. Check result.isError first: it marks a

tool-domain failure the model should see and may retry. Protocol failures (unknown tool, malformed request, timeout) throw McpError; compare error.code with ErrorCode.x.value.

• Inspect every item in result.content (TextContent, ImageContent,

AudioContent, EmbeddedResource, ResourceLink). Prefer result.structuredContent when the tool declares an outputSchema.

• Pass RequestOptions(timeout: ..., onprogress: ..., signal: ...) to

long-running calls. Cancel with a BasicAbortController; the pending future then completes with AbortError.

• Server-initiated features need both a client capability and a handler:

ClientCapabilities(sampling: ...) with client.onSamplingRequest, or ClientCapabilities(elicitation: ...) with client.onElicitRequest. Set handlers before connect, and advertise only what the host implements.

• To hand MCP tools to an LLM, map each Tool to the provider's tool format

with tool.name, tool.description and tool.inputSchema.toJson(), then forward the model's tool calls to client.callTool.

Examples

Launch a local stdio server, list all tools across pages, call one and read a resource:

import 'dart:io';
 
import 'package:mcp_dart/mcp_dart.dart';
 
Future<List<Tool>> listAllTools(McpClient client) async {
  final tools = <Tool>[];
  final seen = <String>{};
  String? cursor;
  do {
    final page = await client.listTools(
      params: cursor == null ? null : ListToolsRequest(cursor: cursor),
    );
    tools.addAll(page.tools);
    cursor = page.nextCursor;
    if (cursor != null && !seen.add(cursor)) {
      throw StateError('tools/list repeated cursor "$cursor"');
    }
  } while (cursor != null);
  return tools;
}
 
Future<void> main() async {
  final client = McpClient(
    const Implementation(name: 'notes-client', version: '1.0.0'),
  );
  try {
    await client.connect(
      StdioClientTransport(
        const StdioServerParameters(
          command: 'dart',
          args: ['run', 'bin/server.dart'],
        ),
      ),
    );
    print('connected to ${client.getServerVersion()?.name} '
        'using MCP ${client.getProtocolVersion()}');
 
    for (final tool in await listAllTools(client)) {
      print('${tool.name}: ${tool.description ?? ''}');
    }
 
    final result = await client.callTool(
      const CallToolRequest(
        name: 'add_note',
        arguments: {'id': 'todo', 'text': 'Ship the release'},
      ),
      options: const RequestOptions(timeout: Duration(seconds: 30)),
    );
    for (final content in result.content) {
      if (content is TextContent) {
        (result.isError ? stderr : stdout).writeln(content.text);
      }
    }
 
    if (client.getServerCapabilities()?.resources != null) {
      final read = await client.readResource(
        const ReadResourceRequest(uri: 'notes://index'),
      );
      for (final contents in read.contents) {
        if (contents is TextResourceContents) {
          print(contents.text);
        }
      }
    }
  } on McpError catch (error) {
    stderr.writeln('MCP error ${error.code}: ${error.message}');
  } finally {
    await client.close();
  }
}

Connect to a remote server, get a prompt, and cancel a slow tool call with progress:

import 'package:mcp_dart/mcp_dart.dart';
 
Future<void> main() async {
  final client = McpClient(
    const Implementation(name: 'remote-client', version: '1.0.0'),
  );
  try {
    await client.connect(
      StreamableHttpClientTransport(Uri.parse('https://mcp.example.com/mcp')),
    );
 
    if (client.getServerCapabilities()?.prompts != null) {
      final prompt = await client.getPrompt(
        const GetPromptRequest(
          name: 'summarize_note',
          arguments: {'id': 'todo'},
        ),
      );
      for (final message in prompt.messages) {
        final content = message.content;
        if (content is TextContent) {
          print('${message.role.name}: ${content.text}');
        }
      }
    }
 
    final controller = BasicAbortController();
    final pending = client.callTool(
      const CallToolRequest(name: 'export_rows', arguments: {'rows': 5000}),
      options: RequestOptions(
        signal: controller.signal,
        onprogress: (progress) {
          print('${progress.progress}/${progress.total} ${progress.message}');
          if (progress.progress >= 1000) {
            controller.abort('User cancelled');
          }
        },
      ),
    );
    try {
      await pending;
    } on AbortError {
      print('export cancelled');
    }
  } finally {
    await client.close();
  }
}

More

• Client guide: https://github.com/leehack/mcp_dart/blob/main/doc/client-guide.md
• Transports and stdio options: https://github.com/leehack/mcp_dart/blob/main/doc/transports.md
• Flutter lifecycle and secure storage: https://github.com/leehack/mcp_dart/blob/main/doc/flutter-recipes.md
• OAuth and Streamable HTTP servers: the mcp-dart-streamable-http skill.