A Dart package for making MCP servers and clients.

Note: This package is still experimental and is likely to evolve quickly.

Implementing Servers

To implement a server, import package:dart_mcp/server.dart and extend the MCPServer class. You must provide the server a StreamChannel<Map<String, Object?>> of decoded JSON-RPC messages to send and receive messages with, such as the one returned by stdioChannel from package:dart_mcp/stdio.dart.

For each specific MCP capability or utility your server supports, there is a corresponding mixin that you can use (ToolsSupport, ResourcesSupport, etc).

Each mixin has doc comments explaining how to use it - some may require you to provide implementations of methods, while others may just expose new methods that you can call.

Register server-specific tools, resources, prompts, and request handlers by overriding MCPServer.initialize(MCPServerInitialization). Always call the super method, and declare what your server supports by editing MCPServer.capabilities. This hook can be used independently of the legacy MCP handshake; the context supplies the protocol version, optional client information, and client capabilities for either lifecycle. A request-scoped transport completes MCPServer.initialized by calling handleInitialized() after this hook and any transport-specific setup have finished, or serves each decoded message on a fresh server instance with handleRequestScopedMessage.

MCPServer.initializeLegacy(InitializeRequest) handles protocol negotiation and the legacy initialize response. Override it only when you need to customize that handshake; feature registration belongs in MCPServer.initialize.

See the examples for some example code (server examples end in _server.dart).

Asking the Client for Input

A tool, prompt or resource handler that needs something from the client answers with an InputRequiredResult naming the elicitation, sampling or roots request it wants filled in. On 2026-07-28 the client answers by retrying the request with the responses attached. On earlier revisions the server sends the same requests itself over the connection and reruns the handler with the answers. A handler written this way serves every supported revision.

Check MCPServer.clientCapabilities before asking for something the client did not declare. If your server needs a capability for every call, read the ClientCapabilities passed to MCPServer.initialize through MCPServerInitialization.clientCapabilities and return an error there, which gives the client a better message than a failing tool call.

Implementing Clients

To implement a client, import package:dart_mcp/client.dart and extend the MCPClient class, or directly call its constructor with a Implementation if you aren't implementing any “capabilities”.

For each specific MCP capability your client supports, there is a corresponding mixin that you can use (RootsSupport, SamplingSupport, etc). Each mixin has doc comments explaining how to use it - some may require you to provide implementations of methods, while others may just expose new methods that you can call.

Connecting to Servers

You can connect this client to STDIO servers by passing the channel returned by stdioChannel to MCPClient.connectServer, or any other StreamChannel<Map<String, Object?>> of decoded JSON-RPC messages. The jsonRpcChannel helper in package:dart_mcp/stdio.dart adapts a StreamChannel<String> whose events each contain one complete JSON document.

The returned ServerConnection should be used for all interactions with the server, starting with a call to ServerConnection.initializeAcrossVersions, which settles the protocol version through discovery or the legacy initialize handshake. If a version could not be negotiated or a server does not support required features, the server connection should be closed (by calling ServerConnection.shutdown).

See initialization lifecycle for information about the client/server initialization protocol.

Invoking Server Capabilities and Utilities

All server capabilities and utilities are exposed as methods or streams on the ServerConnection class.

Before attempting to call methods on the server however, you should first verify the capabilities of the server by reading them from the InitializedServer returned from ServerConnection.initializeAcrossVersions.

Supported Protocol Versions

2024-11-05 2025-03-26 2025-06-18 2025-11-25 2026-07-28

2026-07-28 is served over Streamable HTTP, which has no initialize handshake. The stdio handshake still negotiates up to 2025-11-25.

If support for a given protocol version is dropped, that will be released as a breaking change in this package.

However, we will strive to maintain backwards compatibility where possible.

Base Utilities

This table describes the state of implementation for the base protocol utilities.

Both the MCPServer and MCPClient support these.

Transport Mechanisms

This table describes the supported transport mechanisms.

At its core this package is just built on streams, so any transport mechanism can be used, but some are directly supported out of the box.

Batching Requests

Batch requests are not supported. Batching was removed from MCP in protocol version 2025-06-18, and a batch frame is answered with a single invalid request error response, including for clients which negotiated 2025-03-26.

Authorization

Authorization is not supported at this time. This package is primarily targeted at local MCP server usage for now.

Server Capabilities

This table describes the state of implementation for the server capabilities.

Note: Servers can also invoke all client capabilities, see Invoking Client Capabilities.

Server Utilities

This table describes the state of implementation for the server utilities.

Client Capabilities

This table describes the state of implementation for the client capabilities.

Note: Clients can also invoke all server capabilities and server utilities, see Invoking Server Capabilities and Utilities.