fastmcp.client.client

Classes

ClientSessionState ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L219" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Holds all session-related state for a Client instance.

This allows clean separation of configuration (which is copied) from session state (which should be fresh for each new client instance).

CallToolResult ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L252" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Parsed result from a tool call.

Client ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L262" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

MCP client that delegates connection management to a Transport instance.

The Client class is responsible for MCP protocol logic, while the Transport handles connection establishment and management. Client provides methods for working with resources, prompts, tools and other MCP capabilities.

This client supports reentrant context managers (multiple concurrent async with client: blocks) using reference counting and background session management. This allows efficient session reuse in any scenario with nested or concurrent client usage.

MCP SDK 1.10 introduced automatic list_tools() calls during call_tool() execution. This created a race condition where events could be reset while other tasks were waiting on them, causing deadlocks. The issue was exposed in proxy scenarios but affects any reentrant usage.

The solution uses reference counting to track active context managers, a background task to manage the session lifecycle, events to coordinate between tasks, and ensures all session state changes happen within a lock. Events are only created when needed, never reset outside locks.

This design prevents race conditions where tasks wait on events that get replaced by other tasks, ensuring reliable coordination in concurrent scenarios.

Args:

• transport: Connection source specification, which can be:

  • ClientTransport: Direct transport instance
  • FastMCP: In-process FastMCP server
  • AnyUrl or str: URL to connect to
  • Path: File path for local socket
  • MCPConfig: MCP server configuration
  • dict: Transport configuration

• roots: Optional RootsList or RootsHandler for filesystem access

• sampling_handler: Optional handler for sampling requests

• log_handler: Optional handler for log messages

• message_handler: Optional handler for protocol messages

• progress_handler: Optional handler for progress notifications

• timeout: Optional timeout for requests (seconds or timedelta)

• init_timeout: Optional timeout for initial connection (seconds or timedelta). Set to 0 to disable. If None, uses the value in the FastMCP global settings.

• mode: Protocol-era negotiation at connect time. "auto" (the default) probes server/discover and negotiates the modern era, denylist-falling-back to the initialize handshake for any server that is not positive evidence of a modern peer — safe against a mixed fleet of legacy and modern servers. "legacy" forces the initialize handshake, byte-identical to pre-v4 behavior; opt into it to pin the old handshake. A modern version string (e.g. "2026-07-28") adopts that version directly without a probe.

• prior_discover: A previously obtained DiscoverResult to adopt when mode is a version pin, reused instead of synthesizing a minimal one. Ignored otherwise.

• input_required_max_rounds: Cap on InputRequiredResult (SEP-2322) retry rounds for call_tool / get_prompt / read_resource before the driver gives up. Only reachable on 2026-era servers that emit InputRequiredResult.

• cache: Client-side response caching (SEP-2549), opt-in. None (default) and False disable it; True enables the default in-memory store honoring server ttlMs/cacheScope hints; a CacheConfig customizes it. Honoring is modern-only, so a cache is inert on legacy connections. A custom CacheConfig store requires target_id, since FastMCP transports expose no server URL to derive a shared-store identity from.

• extensions: Opt-in client extensions (SEP-2133), a sequence of mcp.client.extension.ClientExtension instances. Each contributes its capability advertisement, its result claims, and its notification bindings, all of which are threaded into the underlying session. User-supplied notification bindings compose with FastMCP's internal task-status binding rather than replacing it. A claimed call_tool result is resolved transparently through the owning extension's resolver. For an advertise-only entry, use mcp.client.advertise(identifier, settings).

• result_claims: Additional ResultClaims (SEP-2133) keyed by the identifier of an extension already advertised through extensions, merged with that extension's own claims. Rarely needed directly; prefer declaring claims on the extension itself. Claimed shapes are modern-only and inert on a legacy connection.

Examples:

# Connect to FastMCP server
client = Client("http://localhost:8080")

async with client:
    # List available resources
    resources = await client.list_resources()

    # Call a tool
    result = await client.call_tool("my_tool", {"param": "value"})

Methods:

session ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L651" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

session(self) -> ClientSession

Get the current active session. Raises RuntimeError if not connected.

prior_discover ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L661" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

prior_discover(self) -> mcp_types.DiscoverResult | None

The configured result to adopt when mode pins a modern version.

initialize_result ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L666" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

initialize_result(self) -> mcp_types.InitializeResult | None

Get the result of the initialization request.

None on a modern (server/discover) connection, which negotiates via a DiscoverResult rather than an InitializeResult. Use protocol_version, server_info, server_capabilities, and instructions for era-neutral access to the negotiated server metadata.

protocol_version ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L677" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

protocol_version(self) -> str | None

The negotiated protocol version, or None when disconnected.

Set during connect-time negotiation regardless of era: the initialize handshake, server/discover, or a direct version pin all populate it.

server_capabilities ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L687" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

server_capabilities(self) -> mcp_types.ServerCapabilities | None

The server's advertised capabilities, or None when disconnected.

Populated from whichever negotiation result the era produced (the InitializeResult on legacy, the DiscoverResult on modern).

server_info ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L697" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

server_info(self) -> mcp_types.Implementation | None

The session's server identity, or None when disconnected.

Populated from whichever negotiation result the era produced (the InitializeResult on legacy, the DiscoverResult on modern). A directly pinned modern version uses a synthesized identity with an empty name.

instructions ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L708" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

instructions(self) -> str | None

The server's instructions, or None when absent or disconnected.

Populated from whichever negotiation result the era produced (the InitializeResult on legacy, the DiscoverResult on modern).

set_roots ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L717" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

set_roots(self, roots: RootsList | RootsHandler) -> None

Set the roots for the client. This does not automatically call send_roots_list_changed.

set_sampling_callback ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L721" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

set_sampling_callback(self, sampling_callback: SamplingHandler, sampling_capabilities: mcp_types.SamplingCapability | None = None) -> None

Set the sampling callback for the client.

set_elicitation_callback ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L736" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

set_elicitation_callback(self, elicitation_callback: ElicitationHandler) -> None

Set the elicitation callback for the client.

is_connected ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L747" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

is_connected(self) -> bool

Check if the client is currently connected.

new ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L751" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

new(self) -> Client[ClientTransportT]

Create a new client instance with the same configuration but fresh session state.

This creates a new client with the same transport, handlers, and configuration, but with no active session. Useful for creating independent sessions that don't share state with the original client.

Returns:

• A new Client instance with the same configuration but disconnected state.

initialize ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L891" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

initialize(self, timeout: datetime.timedelta | float | int | None = None) -> mcp_types.InitializeResult

Send an initialize request to the server.

This method performs the MCP initialization handshake with the server, exchanging capabilities and server information. It is idempotent - calling it multiple times returns the cached result from the first call.

The initialization happens automatically when entering the client context manager unless auto_initialize=False was set during client construction. Manual calls to this method are only needed when auto-initialization is disabled.

With mode="auto" or a pinned modern version, connect-time negotiation may adopt the modern server/discover era, which has no InitializeResult; in that case this method raises. Read protocol_version, server_info, server_capabilities, and instructions instead, or use mode="legacy" when you need the handshake result.

Args:

• timeout: Optional timeout for the initialization request (seconds or timedelta). If None, uses the client's init_timeout setting.

Returns:

• The server's initialization response containing server info, capabilities, protocol version, and optional instructions.

Raises:

• RuntimeError: If the client is not connected, initialization times out, or the negotiated era carries no InitializeResult (a modern discover connection).

close ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L1363" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

close(self)

ping ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L1369" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

ping(self) -> bool

Send a ping request.

cancel ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L1374" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

cancel(self, request_id: str | int, reason: str | None = None) -> None

Send a cancellation notification for an in-progress request.

progress ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L1389" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

progress(self, progress_token: str | int, progress: float, total: float | None = None, message: str | None = None) -> None

Send a progress notification.

set_logging_level ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L1403" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

set_logging_level(self, level: mcp_types.LoggingLevel) -> None

Send a logging/setLevel request.

Handshake-era servers only. logging/setLevel asks the server to remember a level for the rest of the session, and the 2026-07-28 protocol has no session to remember it in — the method is absent from that era's registry. Log notifications are unaffected: they ride the request's own stream, so a server's ctx.info() still reaches you. Filter by level on the receiving side instead, in your log_handler.

send_roots_list_changed ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L1426" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

send_roots_list_changed(self) -> None

Send a roots/list_changed notification.

complete_mcp ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L1434" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

complete_mcp(self, ref: mcp_types.ResourceTemplateReference | mcp_types.PromptReference, argument: dict[str, str], context_arguments: dict[str, Any] | None = None) -> mcp_types.CompleteResult

Send a completion request and return the complete MCP protocol result.

Args:

• ref: The reference to complete.
• argument: Arguments to pass to the completion request.
• context_arguments: Optional context arguments to include with the completion request. Defaults to None.

Returns:

• mcp_types.CompleteResult: The complete response object from the protocol, containing the completion and any additional metadata.

Raises:

• RuntimeError: If called while the client is not connected.
• MCPError: If the request results in a TimeoutError | JSONRPCError

complete ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L1465" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

complete(self, ref: mcp_types.ResourceTemplateReference | mcp_types.PromptReference, argument: dict[str, str], context_arguments: dict[str, Any] | None = None) -> mcp_types.Completion

Send a completion request to the server.

Args:

• ref: The reference to complete.
• argument: Arguments to pass to the completion request.
• context_arguments: Optional context arguments to include with the completion request. Defaults to None.

Returns:

• mcp_types.Completion: The completion object.

Raises:

• RuntimeError: If called while the client is not connected.
• MCPError: If the request results in a TimeoutError | JSONRPCError

generate_name ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L1492" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

generate_name(cls, name: str | None = None) -> str