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.