ceos/fastmcp
1
0
Fork 0
mirror of https://github.com/PrefectHQ/fastmcp.git synced 2026-08-09 23:29:10 +02:00
Code Issues Projects Releases Packages Wiki Activity
fastmcp/docs/python-sdk/fastmcp-client-client.mdx
marvin-context-protocol[bot] 197184b7ca chore: Update SDK documentation
2026-01-18 21:18:31 +00:00

738 lines
29 KiB
Text
Raw Permalink Blame History

---
title: client
sidebarTitle: client
---
# `fastmcp.client.client`
## Classes
### `ClientSessionState` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L104" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></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><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L121" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Parsed result from a tool call.
### `Client` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L131" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></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.
**Examples:**
```python
# 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><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L353" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
session(self) -> ClientSession
```
Get the current active session. Raises RuntimeError if not connected.
#### `initialize_result` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L363" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
initialize_result(self) -> mcp.types.InitializeResult | None
```
Get the result of the initialization request.
#### `set_roots` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L367" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
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><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L371" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
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><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L387" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
set_elicitation_callback(self, elicitation_callback: ElicitationHandler) -> None
```
Set the elicitation callback for the client.
#### `is_connected` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L395" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
is_connected(self) -> bool
```
Check if the client is currently connected.
#### `new` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L399" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
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><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L444" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
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.
**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 or initialization times out.
#### `close` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L749" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
close(self)
```
#### `ping` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L755" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
ping(self) -> bool
```
Send a ping request.
#### `cancel` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L760" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
cancel(self, request_id: str | int, reason: str | None = None) -> None
```
Send a cancellation notification for an in-progress request.
#### `progress` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L777" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
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><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L789" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
set_logging_level(self, level: mcp.types.LoggingLevel) -> None
```
Send a logging/setLevel request.
#### `send_roots_list_changed` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L793" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
send_roots_list_changed(self) -> None
```
Send a roots/list_changed notification.
#### `list_resources_mcp` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L799" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
list_resources_mcp(self) -> mcp.types.ListResourcesResult
```
Send a resources/list request and return the complete MCP protocol result.
**Args:**
- `cursor`: Optional pagination cursor from a previous request's nextCursor.
**Returns:**
- mcp.types.ListResourcesResult: The complete response object from the protocol,
containing the list of resources and any additional metadata.
**Raises:**
- `RuntimeError`: If called while the client is not connected.
- `McpError`: If the request results in a TimeoutError | JSONRPCError
#### `list_resources` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L822" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
list_resources(self) -> list[mcp.types.Resource]
```
Retrieve all resources available on the server.
This method automatically fetches all pages if the server paginates results,
returning the complete list. For manual pagination control (e.g., to handle
large result sets incrementally), use list_resources_mcp() with the cursor parameter.
**Returns:**
- list\[mcp.types.Resource]: A list of all Resource objects.
**Raises:**
- `RuntimeError`: If called while the client is not connected.
- `McpError`: If the request results in a TimeoutError | JSONRPCError
#### `list_resource_templates_mcp` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L848" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
list_resource_templates_mcp(self) -> mcp.types.ListResourceTemplatesResult
```
Send a resources/listResourceTemplates request and return the complete MCP protocol result.
**Args:**
- `cursor`: Optional pagination cursor from a previous request's nextCursor.
**Returns:**
- mcp.types.ListResourceTemplatesResult: The complete response object from the protocol,
containing the list of resource templates and any additional metadata.
**Raises:**
- `RuntimeError`: If called while the client is not connected.
- `McpError`: If the request results in a TimeoutError | JSONRPCError
#### `list_resource_templates` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L871" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
list_resource_templates(self) -> list[mcp.types.ResourceTemplate]
```
Retrieve all resource templates available on the server.
This method automatically fetches all pages if the server paginates results,
returning the complete list. For manual pagination control (e.g., to handle
large result sets incrementally), use list_resource_templates_mcp() with the
cursor parameter.
**Returns:**
- list\[mcp.types.ResourceTemplate]: A list of all ResourceTemplate objects.
**Raises:**
- `RuntimeError`: If called while the client is not connected.
- `McpError`: If the request results in a TimeoutError | JSONRPCError
#### `read_resource_mcp` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L898" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
read_resource_mcp(self, uri: AnyUrl | str, meta: dict[str, Any] | None = None) -> mcp.types.ReadResourceResult
```
Send a resources/read request and return the complete MCP protocol result.
**Args:**
- `uri`: The URI of the resource to read. Can be a string or an AnyUrl object.
- `meta`: Request metadata (e.g., for SEP-1686 tasks). Defaults to None.
**Returns:**
- mcp.types.ReadResourceResult: The complete response object from the protocol,
containing the resource contents and any additional metadata.
**Raises:**
- `RuntimeError`: If called while the client is not connected.
- `McpError`: If the request results in a TimeoutError | JSONRPCError
#### `read_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L954" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
read_resource(self, uri: AnyUrl | str) -> list[mcp.types.TextResourceContents | mcp.types.BlobResourceContents]
```
#### `read_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L964" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
read_resource(self, uri: AnyUrl | str) -> ResourceTask
```
#### `read_resource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L975" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
read_resource(self, uri: AnyUrl | str) -> list[mcp.types.TextResourceContents | mcp.types.BlobResourceContents] | ResourceTask
```
Read the contents of a resource or resolved template.
**Args:**
- `uri`: The URI of the resource to read. Can be a string or an AnyUrl object.
- `version`: Specific version to read. If None, reads highest version.
- `meta`: Optional request-level metadata.
- `task`: If True, execute as background task (SEP-1686). Defaults to False.
- `task_id`: Optional client-provided task ID (auto-generated if not provided).
- `ttl`: Time to keep results available in milliseconds (default 60s).
**Returns:**
- list\[mcp.types.TextResourceContents | mcp.types.BlobResourceContents] | ResourceTask:
A list of content objects if task=False, or a ResourceTask object if task=True.
**Raises:**
- `RuntimeError`: If called while the client is not connected.
- `McpError`: If the request results in a TimeoutError | JSONRPCError
#### `list_prompts_mcp` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1107" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
list_prompts_mcp(self) -> mcp.types.ListPromptsResult
```
Send a prompts/list request and return the complete MCP protocol result.
**Args:**
- `cursor`: Optional pagination cursor from a previous request's nextCursor.
**Returns:**
- mcp.types.ListPromptsResult: The complete response object from the protocol,
containing the list of prompts and any additional metadata.
**Raises:**
- `RuntimeError`: If called while the client is not connected.
- `McpError`: If the request results in a TimeoutError | JSONRPCError
#### `list_prompts` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1130" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
list_prompts(self) -> list[mcp.types.Prompt]
```
Retrieve all prompts available on the server.
This method automatically fetches all pages if the server paginates results,
returning the complete list. For manual pagination control (e.g., to handle
large result sets incrementally), use list_prompts_mcp() with the cursor parameter.
**Returns:**
- list\[mcp.types.Prompt]: A list of all Prompt objects.
**Raises:**
- `RuntimeError`: If called while the client is not connected.
- `McpError`: If the request results in a TimeoutError | JSONRPCError
#### `get_prompt_mcp` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1157" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
get_prompt_mcp(self, name: str, arguments: dict[str, Any] | None = None, meta: dict[str, Any] | None = None) -> mcp.types.GetPromptResult
```
Send a prompts/get request and return the complete MCP protocol result.
**Args:**
- `name`: The name of the prompt to retrieve.
- `arguments`: Arguments to pass to the prompt. Defaults to None.
- `meta`: Request metadata (e.g., for SEP-1686 tasks). Defaults to None.
**Returns:**
- mcp.types.GetPromptResult: The complete response object from the protocol,
containing the prompt messages and any additional metadata.
**Raises:**
- `RuntimeError`: If called while the client is not connected.
- `McpError`: If the request results in a TimeoutError | JSONRPCError
#### `get_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1226" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
get_prompt(self, name: str, arguments: dict[str, Any] | None = None) -> mcp.types.GetPromptResult
```
#### `get_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1237" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
get_prompt(self, name: str, arguments: dict[str, Any] | None = None) -> PromptTask
```
#### `get_prompt` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1249" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
get_prompt(self, name: str, arguments: dict[str, Any] | None = None) -> mcp.types.GetPromptResult | PromptTask
```
Retrieve a rendered prompt message list from the server.
**Args:**
- `name`: The name of the prompt to retrieve.
- `arguments`: Arguments to pass to the prompt. Defaults to None.
- `version`: Specific prompt version to get. If None, gets highest version.
- `meta`: Optional request-level metadata.
- `task`: If True, execute as background task (SEP-1686). Defaults to False.
- `task_id`: Optional client-provided task ID (auto-generated if not provided).
- `ttl`: Time to keep results available in milliseconds (default 60s).
**Returns:**
- mcp.types.GetPromptResult | PromptTask: The complete response object if task=False,
or a PromptTask object if task=True.
**Raises:**
- `RuntimeError`: If called while the client is not connected.
- `McpError`: If the request results in a TimeoutError | JSONRPCError
#### `complete_mcp` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1372" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
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><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1403" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
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
#### `list_tools_mcp` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1431" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
list_tools_mcp(self) -> mcp.types.ListToolsResult
```
Send a tools/list request and return the complete MCP protocol result.
**Args:**
- `cursor`: Optional pagination cursor from a previous request's nextCursor.
**Returns:**
- mcp.types.ListToolsResult: The complete response object from the protocol,
containing the list of tools and any additional metadata.
**Raises:**
- `RuntimeError`: If called while the client is not connected.
- `McpError`: If the request results in a TimeoutError | JSONRPCError
#### `list_tools` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1454" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
list_tools(self) -> list[mcp.types.Tool]
```
Retrieve all tools available on the server.
This method automatically fetches all pages if the server paginates results,
returning the complete list. For manual pagination control (e.g., to handle
large result sets incrementally), use list_tools_mcp() with the cursor parameter.
**Returns:**
- list\[mcp.types.Tool]: A list of all Tool objects.
**Raises:**
- `RuntimeError`: If called while the client is not connected.
- `McpError`: If the request results in a TimeoutError | JSONRPCError
#### `call_tool_mcp` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1482" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
call_tool_mcp(self, name: str, arguments: dict[str, Any], progress_handler: ProgressHandler | None = None, timeout: datetime.timedelta | float | int | None = None, meta: dict[str, Any] | None = None) -> mcp.types.CallToolResult
```
Send a tools/call request and return the complete MCP protocol result.
This method returns the raw CallToolResult object, which includes an isError flag
and other metadata. It does not raise an exception if the tool call results in an error.
**Args:**
- `name`: The name of the tool to call.
- `arguments`: Arguments to pass to the tool.
- `timeout`: The timeout for the tool call. Defaults to None.
- `progress_handler`: The progress handler to use for the tool call. Defaults to None.
- `meta`: Additional metadata to include with the request.
This is useful for passing contextual information (like user IDs, trace IDs, or preferences)
that shouldn't be tool arguments but may influence server-side processing. The server
can access this via `context.request_context.meta`. Defaults to None.
**Returns:**
- mcp.types.CallToolResult: The complete response object from the protocol,
containing the tool result and any additional metadata.
**Raises:**
- `RuntimeError`: If called while the client is not connected.
- `McpError`: If the tool call requests results in a TimeoutError | JSONRPCError
#### `call_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1587" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
call_tool(self, name: str, arguments: dict[str, Any] | None = None) -> CallToolResult
```
#### `call_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1601" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
call_tool(self, name: str, arguments: dict[str, Any] | None = None) -> ToolTask
```
#### `call_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1616" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
call_tool(self, name: str, arguments: dict[str, Any] | None = None) -> CallToolResult | ToolTask
```
Call a tool on the server.
Unlike call_tool_mcp, this method raises a ToolError if the tool call results in an error.
**Args:**
- `name`: The name of the tool to call.
- `arguments`: Arguments to pass to the tool. Defaults to None.
- `version`: Specific tool version to call. If None, calls highest version.
- `timeout`: The timeout for the tool call. Defaults to None.
- `progress_handler`: The progress handler to use for the tool call. Defaults to None.
- `raise_on_error`: Whether to raise an exception if the tool call results in an error. Defaults to True.
- `meta`: Additional metadata to include with the request.
This is useful for passing contextual information (like user IDs, trace IDs, or preferences)
that shouldn't be tool arguments but may influence server-side processing. The server
can access this via `context.request_context.meta`. Defaults to None.
- `task`: If True, execute as background task (SEP-1686). Defaults to False.
- `task_id`: Optional client-provided task ID (auto-generated if not provided).
- `ttl`: Time to keep results available in milliseconds (default 60s).
**Returns:**
- CallToolResult | ToolTask: The content returned by the tool if task=False,
or a ToolTask object if task=True. If the tool returns structured
outputs, they are returned as a dataclass (if an output schema
is available) or a dictionary; otherwise, a list of content
blocks is returned. Note: to receive both structured and
unstructured outputs, use call_tool_mcp instead and access the
raw result object.
**Raises:**
- `ToolError`: If the tool call results in an error.
- `McpError`: If the tool call request results in a TimeoutError | JSONRPCError
- `RuntimeError`: If called while the client is not connected.
#### `get_task_status` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1753" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
get_task_status(self, task_id: str) -> GetTaskResult
```
Query the status of a background task.
Sends a 'tasks/get' MCP protocol request over the existing transport.
**Args:**
- `task_id`: The task ID returned from call_tool_as_task
**Returns:**
- Status information including taskId, status, pollInterval, etc.
**Raises:**
- `RuntimeError`: If client not connected
- `McpError`: If the request results in a TimeoutError | JSONRPCError
#### `get_task_result` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1776" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
get_task_result(self, task_id: str) -> Any
```
Retrieve the raw result of a completed background task.
Sends a 'tasks/result' MCP protocol request over the existing transport.
Returns the raw result - callers should parse it appropriately.
**Args:**
- `task_id`: The task ID returned from call_tool_as_task
**Returns:**
- The raw result (could be tool, prompt, or resource result)
**Raises:**
- `RuntimeError`: If client not connected, task not found, or task failed
- `McpError`: If the request results in a TimeoutError | JSONRPCError
#### `list_tasks` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1805" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
list_tasks(self, cursor: str | None = None, limit: int = 50) -> dict[str, Any]
```
List background tasks.
Sends a 'tasks/list' MCP protocol request to the server. If the server
returns an empty list (indicating client-side tracking), falls back to
querying status for locally tracked task IDs.
**Args:**
- `cursor`: Optional pagination cursor
- `limit`: Maximum number of tasks to return (default 50)
**Returns:**
- Response with structure:
- tasks: List of task status dicts with taskId, status, etc.
- nextCursor: Optional cursor for next page
**Raises:**
- `RuntimeError`: If client not connected
- `McpError`: If the request results in a TimeoutError | JSONRPCError
#### `cancel_task` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1855" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
cancel_task(self, task_id: str) -> mcp.types.CancelTaskResult
```
Cancel a task, transitioning it to cancelled state.
Sends a 'tasks/cancel' MCP protocol request. Task will halt execution
and transition to cancelled state.
**Args:**
- `task_id`: The task ID to cancel
**Returns:**
- The task status showing cancelled state
**Raises:**
- `RuntimeError`: If task doesn't exist
- `McpError`: If the request results in a TimeoutError | JSONRPCError
#### `generate_name` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/client.py#L1880" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
generate_name(cls, name: str | None = None) -> str
```
Reference in a new issue View git blame Copy permalink