> ## Documentation Index
> Fetch the complete documentation index at: https://gofastmcp.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# client

# `fastmcp.client.client`

## Classes

### `ClientSessionState` <sup>[https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp\_slim/fastmcp/client/client.py#L219](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L219)</sup>

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` <sup>[https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp\_slim/fastmcp/client/client.py#L252](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L252)</sup>

Parsed result from a tool call.

### `Client` <sup>[https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp\_slim/fastmcp/client/client.py#L262](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L262)</sup>

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 `ResultClaim`s (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:**

```python theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
# 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` <sup>[https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp\_slim/fastmcp/client/client.py#L653](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L653)</sup>

```python theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
session(self) -> ClientSession
```

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

#### `prior_discover` <sup>[https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp\_slim/fastmcp/client/client.py#L663](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L663)</sup>

```python theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
prior_discover(self) -> mcp_types.DiscoverResult | None
```

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

#### `initialize_result` <sup>[https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp\_slim/fastmcp/client/client.py#L668](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L668)</sup>

```python theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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` <sup>[https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp\_slim/fastmcp/client/client.py#L679](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L679)</sup>

```python theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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` <sup>[https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp\_slim/fastmcp/client/client.py#L689](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L689)</sup>

```python theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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` <sup>[https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp\_slim/fastmcp/client/client.py#L699](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L699)</sup>

```python theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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` <sup>[https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp\_slim/fastmcp/client/client.py#L710](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L710)</sup>

```python theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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` <sup>[https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp\_slim/fastmcp/client/client.py#L719](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L719)</sup>

```python theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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` <sup>[https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp\_slim/fastmcp/client/client.py#L723](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L723)</sup>

```python theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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` <sup>[https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp\_slim/fastmcp/client/client.py#L738](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L738)</sup>

```python theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
set_elicitation_callback(self, elicitation_callback: ElicitationHandler) -> None
```

Set the elicitation callback for the client.

#### `is_connected` <sup>[https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp\_slim/fastmcp/client/client.py#L749](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L749)</sup>

```python theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
is_connected(self) -> bool
```

Check if the client is currently connected.

#### `new` <sup>[https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp\_slim/fastmcp/client/client.py#L753](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L753)</sup>

```python theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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` <sup>[https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp\_slim/fastmcp/client/client.py#L893](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L893)</sup>

```python theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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` <sup>[https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp\_slim/fastmcp/client/client.py#L1393](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L1393)</sup>

```python theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
close(self)
```

#### `ping` <sup>[https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp\_slim/fastmcp/client/client.py#L1399](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L1399)</sup>

```python theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
ping(self) -> bool
```

Send a ping request.

#### `cancel` <sup>[https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp\_slim/fastmcp/client/client.py#L1404](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L1404)</sup>

```python theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
cancel(self, request_id: str | int, reason: str | None = None) -> None
```

Send a cancellation notification for an in-progress request.

#### `progress` <sup>[https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp\_slim/fastmcp/client/client.py#L1419](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L1419)</sup>

```python theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
progress(self, progress_token: str | int, progress: float, total: float | None = None, message: str | None = None) -> None
```

Send a progress notification.

#### `set_logging_level` <sup>[https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp\_slim/fastmcp/client/client.py#L1433](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L1433)</sup>

```python theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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` <sup>[https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp\_slim/fastmcp/client/client.py#L1456](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L1456)</sup>

```python theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
send_roots_list_changed(self) -> None
```

Send a roots/list\_changed notification.

#### `complete_mcp` <sup>[https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp\_slim/fastmcp/client/client.py#L1464](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L1464)</sup>

```python theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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` <sup>[https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp\_slim/fastmcp/client/client.py#L1495](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L1495)</sup>

```python theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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` <sup>[https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp\_slim/fastmcp/client/client.py#L1522](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/client.py#L1522)</sup>

```python theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
generate_name(cls, name: str | None = None) -> str
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.