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 stays request/response only.
Summary
Functions
Returns the last cached task status, if any.
Calls a tool with the given arguments.
Cancels a remote task and updates the local cache.
Cancels a background task.
Returns the negotiated server capabilities.
Returns a specification to start this module under a supervisor.
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.
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 visible prompts.
Lists visible resource templates.
Lists visible resources.
Lists background tasks.
Lists visible tools.
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.
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.
Sends input to a background task waiting for user interaction.
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 elicitation callback used for server-initiated interaction requests.
Registers the callback used for server log messages.
Registers the callback used for generic notifications.
Registers the callback used for progress notifications.
Registers the sampling callback used for server-initiated sampling requests.
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.
Waits for a tracked task to reach a target status or any terminal status.
Functions
Returns the last cached task status, if any.
Calls a tool with the given arguments.
Cancels a remote task and updates the local cache.
Cancels a background task.
Returns the negotiated server capabilities.
Returns a specification to start this module under a supervisor.
See Supervisor.
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.
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 visible prompts.
Lists visible resource templates.
Lists visible resources.
Lists background tasks.
Lists visible tools.
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.
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.
Sends input to a background task waiting for user interaction.
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 elicitation callback used for server-initiated interaction requests.
Registers the callback used for server log messages.
Registers the callback used for generic notifications.
Registers the callback used for progress notifications.
Registers the sampling callback used for server-initiated sampling requests.
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.
Waits for a tracked task to reach a target status or any terminal status.