MCP client implementation.
A GenServer that manages a connection to an MCP server via a pluggable transport. Handles the initialization handshake, request/response matching, and provides the full MCP client API.
Usage
{:ok, client} = MCP.Client.start_link(
transport: {MCP.Transport.Stdio, command: "mcp-server", args: []},
client_info: %{name: "my_app", version: "1.0.0"}
)
{:ok, result} = MCP.Client.connect(client)
{:ok, tools} = MCP.Client.list_tools(client)
{:ok, result} = MCP.Client.call_tool(client, "my_tool", %{"arg" => "val"})Options
:transport—{module, opts}transport spec. The client starts the transport in its init, setting itself as the owner.:client_info—%Implementation{}or map with:nameand:version.:client_capabilities—%ClientCapabilities{}(default: auto-detected from callbacks).:notification_handler— pid or(method, params -> any())for server notifications.:request_handlers—%{method => callback}for server-initiated requests (sampling, roots, elicitation). Prefer the convenience callback options below.:request_timeout— default timeout in ms for requests (default: 30_000).
Client Feature Callbacks
These convenience options automatically set the appropriate capabilities and request handlers. When provided, the client will advertise the corresponding capability during initialization and dispatch server-initiated requests to the callback.
:on_sampling—fn(params) -> {:ok, result} | {:error, error}forsampling/createMessagerequests. Result should include"role","content","model", and"stopReason".:on_roots_list—fn(params) -> {:ok, result}forroots/listrequests. Result should include"roots"(list of root maps with"uri"and optional"name").:on_elicitation—fn(params) -> {:ok, result} | {:error, error}forelicitation/createrequests. Result should include"action"and optional"content".
Summary
Functions
Calls a tool on the server.
Cancels a pending request by its ID.
Returns a specification to start this module under a supervisor.
Closes the client and its transport.
Performs the MCP initialization handshake.
Gets a specific prompt by name with optional arguments.
Lists all prompts, automatically paginating through all pages.
Lists all resource templates, automatically paginating through all pages.
Lists all resources, automatically paginating through all pages.
Lists all tools, automatically paginating through all pages.
Lists available prompts from the server.
Lists resource templates from the server.
Lists available resources from the server.
Lists available tools from the server.
Notifies the server that the client's roots have changed.
Sends a ping request. Works even before initialization.
Reads a resource by URI.
Returns the negotiated server capabilities.
Returns the server info from initialization.
Starts the client GenServer and its transport.
Returns the current client status.
Subscribes to updates for a resource URI.
Returns the transport pid (useful for testing with MockTransport).
Unsubscribes from updates for a resource URI.
Functions
Calls a tool on the server.
Returns {:ok, %Tools.CallResult{}} on success.
Cancels a pending request by its ID.
Sends a notifications/cancelled notification to the server with the
given request ID and optional reason.
Returns a specification to start this module under a supervisor.
See Supervisor.
Closes the client and its transport.
Performs the MCP initialization handshake.
Sends initialize request to the server and waits for the response.
On success, sends initialized notification and returns server info.
Returns {:ok, result} where result contains :server_info,
:server_capabilities, and :protocol_version.
Gets a specific prompt by name with optional arguments.
Returns {:ok, %Prompts.GetResult{}} on success.
Lists all prompts, automatically paginating through all pages.
Returns {:ok, [Prompt.t()]} on success.
Lists all resource templates, automatically paginating through all pages.
Returns {:ok, [ResourceTemplate.t()]} on success.
Lists all resources, automatically paginating through all pages.
Returns {:ok, [Resource.t()]} on success.
Lists all tools, automatically paginating through all pages.
Returns {:ok, [Tool.t()]} on success.
Lists available prompts from the server.
Options:
:cursor— pagination cursor.:timeout— request timeout in ms.
Returns {:ok, %Prompts.ListResult{}} on success.
Lists resource templates from the server.
Options:
:cursor— pagination cursor.:timeout— request timeout in ms.
Returns {:ok, %Resources.ListTemplatesResult{}} on success.
Lists available resources from the server.
Options:
:cursor— pagination cursor.:timeout— request timeout in ms.
Returns {:ok, %Resources.ListResult{}} on success.
Lists available tools from the server.
Options:
:cursor— pagination cursor from a previous response.:timeout— request timeout in ms.
Returns {:ok, %Tools.ListResult{}} on success.
Notifies the server that the client's roots have changed.
The server can then re-request the roots list via roots/list.
Only meaningful if the client advertised roots capability with listChanged: true.
Sends a ping request. Works even before initialization.
Reads a resource by URI.
Returns {:ok, %Resources.ReadResult{}} on success.
Returns the negotiated server capabilities.
Returns the server info from initialization.
Starts the client GenServer and its transport.
Returns the current client status.
Subscribes to updates for a resource URI.
Returns the transport pid (useful for testing with MockTransport).
Unsubscribes from updates for a resource URI.