Connected MCP client.
FastestMCP.Client is the stateful client-side companion to the server
runtime. It owns:
- the negotiated session id and initialize result
- the underlying transport state
- bounded in-flight request tracking
- optional callbacks for sampling, elicitation, logs, progress, and generic notifications
- optional session stream management for streamable HTTP
The client is a GenServer, but most callers use it as a small opaque handle
and interact through the exported helpers in this module.
Example
client =
FastestMCP.Client.connect!("http://127.0.0.1:4100/mcp",
client_info: %{"name" => "docs-client", "version" => "1.0.0"}
)
tools_page = FastestMCP.Client.list_tools(client)
result = FastestMCP.Client.call_tool(client, "sum", %{"a" => 20, "b" => 22})Resolve completion values with the same connected session and auth context:
FastestMCP.Client.complete(
client,
%{type: "prompt", name: "draft_release"},
%{name: "environment", value: "pr"}
)Handler Callbacks
When the server asks the client to do more than plain request/response work, install callbacks with:
set_sampling_handler/2set_elicitation_handler/2set_log_handler/2set_progress_handler/2set_notification_handler/2
Those callbacks are how the client participates in model interaction and long-running task flows.
For streamable HTTP clients, this module also owns resource subscriptions and session-stream notifications. Stdio and connected in-process clients carry bidirectional callbacks over their line-framed connection but do not expose a separate session stream.
Summary
Functions
Waits for an asynchronous request and returns its raw MCP result.
Waits until a client is ready or raises a normalized timeout or connection error.
Returns the last cached task status, if any.
Calls a tool with the given arguments.
Calls a tool and returns one stable, protocol-faithful terminal result.
Calls a tool and returns its remote task handle.
Returns whether a server-initiated callback has been cancelled.
Explicitly cancels an in-flight non-task request.
Cancels a remote task and updates the local cache.
Cancels a background task.
Returns the negotiated server capabilities.
Returns a permanent worker specification for a supervised MCP client.
Closes the session event stream.
Requests completion values for a prompt argument or resource-template parameter.
Connects a client to the given transport target.
Connects a client to the given transport target and raises on failure.
Returns whether the client process is still alive.
Disconnects a client and releases its transport resources.
Runs modern stateless server discovery and selects MCP 2026 for this connection.
Returns the last modern server discovery result cached by the client.
Fetches background-task state.
Processes synchronous GenServer calls for the state owned by this module.
Processes asynchronous messages delivered to the process owned by this module.
Initializes the state used by this module before it starts processing work.
Runs the MCP initialize handshake.
Returns the last initialize result cached by the client.
Lists every visible prompt across the server's bounded pagination sequence.
Lists every visible resource template across the bounded pagination sequence.
Lists every visible resource across the server's bounded pagination sequence.
Lists every visible tool across the server's bounded pagination sequence.
Lists visible prompts.
Lists visible resource templates.
Lists visible resources.
Lists background tasks.
Lists visible tools.
Starts a modern subscription/listen request and returns its request handle.
Registers a callback for remote task status changes.
Opens the session event stream when the transport supports it.
Runs a ping request.
Returns the negotiated protocol version.
Reads a resource by URI.
Returns whether the client has completed negotiation and its transport is usable.
Caches fresh task status after a tasks/get round trip.
Fetches and caches the final result for a remote task handle.
Renders a prompt with the given arguments.
Emits progress for a server-initiated callback.
Sends a low-level MCP request and returns its raw result.
Starts a low-level MCP request and returns an opaque cancellable handle.
Returns the negotiated session id.
Returns whether the client session stream is currently open.
Replaces the access token used for future requests.
Merges or replaces auth input used for future requests.
Registers the callback for completion of an accepted URL elicitation.
Registers the elicitation callback used for server-initiated interaction requests.
Registers the callback used for server log messages.
Requests that the server emit logs at level or higher.
Registers the callback used for generic notifications.
Registers the callback used for progress notifications.
Replaces the advertised filesystem roots and notifies the server on material changes.
Registers the sampling callback used for server-initiated sampling requests.
Registers the callback used for URL-mode elicitation requests.
Starts a supervised MCP client from a keyword configuration.
Subscribes the current session to updates for one concrete resource URI.
Returns the normalized result for a background task.
Cleans up module state on shutdown.
Builds or refreshes a remote task handle tracked by this client.
Removes one resource subscription from the current session.
Supplies responses to a remote task's outstanding input requests.
Waits for a tracked task to reach a target status or any terminal status.
Types
@type ref() :: t() | GenServer.server()
@type t() :: %FastestMCP.Client{pid: pid()}
Functions
Waits for an asynchronous request and returns its raw MCP result.
Waits until a client is ready or raises a normalized timeout or connection error.
Returns the last cached task status, if any.
Calls a tool with the given arguments.
Calls a tool and returns one stable, protocol-faithful terminal result.
Calls a tool and returns its remote task handle.
Returns whether a server-initiated callback has been cancelled.
Explicitly cancels an in-flight non-task request.
Cancels a remote task and updates the local cache.
Cancels a background task.
Returns the negotiated server capabilities.
Returns a permanent worker specification for a supervised MCP client.
Closes the session event stream.
Requests completion values for a prompt argument or resource-template parameter.
Connects a client to the given transport target.
Connects a client to the given transport target and raises on failure.
Returns whether the client process is still alive.
Disconnects a client and releases its transport resources.
Runs modern stateless server discovery and selects MCP 2026 for this connection.
Returns the last modern server discovery result cached by the client.
Fetches background-task state.
Processes synchronous GenServer calls for the state owned by this module.
Processes asynchronous messages delivered to the process owned by this module.
Initializes the state used by this module before it starts processing work.
Runs the MCP initialize handshake.
Returns the last initialize result cached by the client.
Lists every visible prompt across the server's bounded pagination sequence.
Lists every visible resource template across the bounded pagination sequence.
Lists every visible resource across the server's bounded pagination sequence.
Lists every visible tool across the server's bounded pagination sequence.
Lists visible prompts.
Lists visible resource templates.
Lists visible resources.
Lists background tasks.
Lists visible tools.
Starts a modern subscription/listen request and returns its request handle.
Registers a callback for remote task status changes.
Opens the session event stream when the transport supports it.
Runs a ping request.
Returns the negotiated protocol version.
Reads a resource by URI.
Returns whether the client has completed negotiation and its transport is usable.
Caches fresh task status after a tasks/get round trip.
Fetches and caches the final result for a remote task handle.
Renders a prompt with the given arguments.
Emits progress for a server-initiated callback.
Sends a low-level MCP request and returns its raw result.
Starts a low-level MCP request and returns an opaque cancellable handle.
Returns the negotiated session id.
Returns whether the client session stream is currently open.
Replaces the access token used for future requests.
Merges or replaces auth input used for future requests.
Registers the callback for completion of an accepted URL elicitation.
Registers the elicitation callback used for server-initiated interaction requests.
Registers the callback used for server log messages.
Requests that the server emit logs at level or higher.
Registers the callback used for generic notifications.
Registers the callback used for progress notifications.
Replaces the advertised filesystem roots and notifies the server on material changes.
Registers the sampling callback used for server-initiated sampling requests.
Registers the callback used for URL-mode elicitation requests.
Starts a supervised MCP client from a keyword configuration.
Subscribes the current session to updates for one concrete resource URI.
Returns the normalized result for a background task.
Cleans up module state on shutdown.
Builds or refreshes a remote task handle tracked by this client.
Removes one resource subscription from the current session.
Supplies responses to a remote task's outstanding input requests.
Waits for a tracked task to reach a target status or any terminal status.