mirror of
https://github.com/PrefectHQ/fastmcp.git
synced 2026-08-22 13:34:17 +02:00
265 lines
11 KiB
Text
265 lines
11 KiB
Text
---
|
|
title: Client Overview
|
|
sidebarTitle: Overview
|
|
description: Learn how to use the FastMCP Client to interact with MCP servers.
|
|
icon: user-robot
|
|
---
|
|
|
|
import { VersionBadge } from '/snippets/version-badge.mdx'
|
|
|
|
<VersionBadge version="2.0.0" />
|
|
|
|
The `fastmcp.Client` provides a high-level, asynchronous interface for interacting with any Model Context Protocol (MCP) server, whether it's built with FastMCP or another implementation. It simplifies communication by handling protocol details and connection management.
|
|
|
|
## FastMCP Client
|
|
|
|
The FastMCP Client architecture separates the protocol logic (`Client`) from the connection mechanism (`Transport`).
|
|
|
|
- **`Client`**: Handles sending MCP requests (like `tools/call`, `resources/read`), receiving responses, and managing callbacks.
|
|
- **`Transport`**: Responsible for establishing and maintaining the connection to the server (e.g., via WebSockets, SSE, Stdio, or in-memory).
|
|
|
|
|
|
### Transports
|
|
|
|
Clients must be initialized with a `transport`. You can either provide an already instantiated transport object, or provide a transport source and let FastMCP attempt to infer the correct transport to use.
|
|
|
|
The following inference rules are used to determine the appropriate `ClientTransport` based on the input type:
|
|
|
|
1. **`ClientTransport` Instance**: If you provide an already instantiated transport object, it's used directly.
|
|
2. **`FastMCP` Instance**: Creates a `FastMCPTransport` for efficient in-memory communication (ideal for testing).
|
|
3. **`Path` or `str` pointing to an existing file**:
|
|
* If it ends with `.py`: Creates a `PythonStdioTransport` to run the script using `python`.
|
|
* If it ends with `.js`: Creates a `NodeStdioTransport` to run the script using `node`.
|
|
4. **`AnyUrl` or `str` pointing to a URL**:
|
|
* If it starts with `http://` or `https://`: Creates an `SSETransport`.
|
|
* If it starts with `ws://` or `wss://`: Creates a `WSTransport`.
|
|
5. **Other**: Raises a `ValueError` if the type cannot be inferred.
|
|
|
|
```python
|
|
import asyncio
|
|
from fastmcp import Client, FastMCP
|
|
|
|
# Example transports (more details in Transports page)
|
|
server_instance = FastMCP(name="TestServer") # In-memory server
|
|
sse_url = "http://localhost:8000/sse" # SSE server URL
|
|
ws_url = "ws://localhost:9000" # WebSocket server URL
|
|
server_script = "my_mcp_server.py" # Path to a Python server file
|
|
|
|
# Client automatically infers the transport type
|
|
client_in_memory = Client(server_instance)
|
|
client_sse = Client(sse_url)
|
|
client_ws = Client(ws_url)
|
|
client_stdio = Client(server_script)
|
|
|
|
print(client_in_memory.transport)
|
|
print(client_sse.transport)
|
|
print(client_ws.transport)
|
|
print(client_stdio.transport)
|
|
|
|
# Expected Output (types may vary slightly based on environment):
|
|
# <FastMCP(server='TestServer')>
|
|
# <SSE(url='http://localhost:8000/sse')>
|
|
# <WebSocket(url='ws://localhost:9000')>
|
|
# <PythonStdioTransport(command='python', args=['/path/to/your/my_mcp_server.py'])>
|
|
```
|
|
<Tip>
|
|
For more control over connection details (like headers for SSE, environment variables for Stdio), you can instantiate the specific `ClientTransport` class yourself and pass it to the `Client`. See the [Transports](/clients/transports) page for details.
|
|
</Tip>
|
|
|
|
## Client Usage
|
|
|
|
### Connection Lifecycle
|
|
|
|
The client operates asynchronously and must be used within an `async with` block. This context manager handles establishing the connection, initializing the MCP session, and cleaning up resources upon exit.
|
|
|
|
```python
|
|
import asyncio
|
|
from fastmcp import Client
|
|
|
|
client = Client("my_mcp_server.py") # Assumes my_mcp_server.py exists
|
|
|
|
async def main():
|
|
# Connection is established here
|
|
async with client:
|
|
print(f"Client connected: {client.is_connected()}")
|
|
|
|
# Make MCP calls within the context
|
|
tools = await client.list_tools()
|
|
print(f"Available tools: {tools}")
|
|
|
|
if any(tool.name == "greet" for tool in tools):
|
|
result = await client.call_tool("greet", {"name": "World"})
|
|
print(f"Greet result: {result}")
|
|
|
|
# Connection is closed automatically here
|
|
print(f"Client connected: {client.is_connected()}")
|
|
|
|
if __name__ == "__main__":
|
|
asyncio.run(main())
|
|
```
|
|
|
|
You can make multiple calls to the server within the same `async with` block using the established session.
|
|
|
|
### Client Methods
|
|
|
|
The `Client` provides methods corresponding to standard MCP requests:
|
|
|
|
#### Tool Operations
|
|
|
|
* **`list_tools()`**: Retrieves a list of tools available on the server.
|
|
```python
|
|
tools = await client.list_tools()
|
|
# tools -> list[mcp.types.Tool]
|
|
```
|
|
* **`call_tool(name: str, arguments: dict[str, Any] | None = None)`**: Executes a tool on the server.
|
|
```python
|
|
result = await client.call_tool("add", {"a": 5, "b": 3})
|
|
# result -> list[mcp.types.TextContent | mcp.types.ImageContent | ...]
|
|
print(result[0].text) # Assuming TextContent, e.g., '8'
|
|
```
|
|
* Arguments are passed as a dictionary. FastMCP servers automatically handle JSON string parsing for complex types if needed.
|
|
* Returns a list of content objects (usually `TextContent` or `ImageContent`).
|
|
|
|
#### Resource Operations
|
|
|
|
* **`list_resources()`**: Retrieves a list of static resources.
|
|
```python
|
|
resources = await client.list_resources()
|
|
# resources -> list[mcp.types.Resource]
|
|
```
|
|
* **`list_resource_templates()`**: Retrieves a list of resource templates.
|
|
```python
|
|
templates = await client.list_resource_templates()
|
|
# templates -> list[mcp.types.ResourceTemplate]
|
|
```
|
|
* **`read_resource(uri: str | AnyUrl)`**: Reads the content of a resource or a resolved template.
|
|
```python
|
|
# Read a static resource
|
|
readme_content = await client.read_resource("file:///path/to/README.md")
|
|
# readme_content -> list[mcp.types.TextResourceContents | mcp.types.BlobResourceContents]
|
|
print(readme_content[0].text) # Assuming text
|
|
|
|
# Read a resource generated from a template
|
|
weather_content = await client.read_resource("data://weather/london")
|
|
print(weather_content[0].text) # Assuming text JSON
|
|
```
|
|
|
|
#### Prompt Operations
|
|
|
|
* **`list_prompts()`**: Retrieves available prompt templates.
|
|
* **`get_prompt(name: str, arguments: dict[str, Any] | None = None)`**: Retrieves a rendered prompt message list.
|
|
|
|
### Callbacks
|
|
|
|
MCP allows servers to make requests *back* to the client for certain capabilities. The `Client` constructor accepts callback functions to handle these server requests:
|
|
|
|
#### Roots
|
|
|
|
* **`roots: RootsList | RootsHandler | None`**: Provides the server with a list of root directories the client grants access to. This can be a static list or a function that dynamically determines roots.
|
|
```python
|
|
from pathlib import Path
|
|
from fastmcp.client.roots import RootsHandler, RootsList
|
|
from mcp.shared.context import RequestContext # For type hint
|
|
|
|
# Option 1: Static list
|
|
static_roots: RootsList = [str(Path.home() / "Documents")]
|
|
|
|
# Option 2: Dynamic function
|
|
def dynamic_roots_handler(context: RequestContext) -> RootsList:
|
|
# Logic to determine accessible roots based on context
|
|
print(f"Server requested roots (Request ID: {context.request_id})")
|
|
return [str(Path.home() / "Downloads")]
|
|
|
|
client_with_roots = Client(
|
|
"my_server.py",
|
|
roots=dynamic_roots_handler # or roots=static_roots
|
|
)
|
|
|
|
# Tell the server the roots might have changed (if needed)
|
|
# async with client_with_roots:
|
|
# await client_with_roots.send_roots_list_changed()
|
|
```
|
|
See `fastmcp.client.roots` for helpers.
|
|
|
|
#### LLM Sampling
|
|
|
|
* **`sampling_handler: SamplingHandler | None`**: Handles `sampling/createMessage` requests from the server. This callback receives messages from the server and should return an LLM completion.
|
|
```python
|
|
from fastmcp.client.sampling import SamplingHandler, MessageResult
|
|
from mcp.types import SamplingMessage, SamplingParams, TextContent
|
|
from mcp.shared.context import RequestContext # For type hint
|
|
|
|
async def my_llm_handler(
|
|
messages: list[SamplingMessage],
|
|
params: SamplingParams,
|
|
context: RequestContext
|
|
) -> str | MessageResult:
|
|
print(f"Server requested sampling (Request ID: {context.request_id})")
|
|
# In a real scenario, call your LLM API here
|
|
last_user_message = next((m for m in reversed(messages) if m.role == 'user'), None)
|
|
prompt = last_user_message.content.text if last_user_message and isinstance(last_user_message.content, TextContent) else "Default prompt"
|
|
|
|
# Simulate LLM response
|
|
response_text = f"LLM processed: {prompt[:50]}..."
|
|
# Return simple string (becomes TextContent) or a MessageResult object
|
|
return response_text
|
|
|
|
client_with_sampling = Client(
|
|
"my_server.py",
|
|
sampling_handler=my_llm_handler
|
|
)
|
|
```
|
|
See `fastmcp.client.sampling` for helpers.
|
|
|
|
#### Logging
|
|
|
|
* **`log_handler: LoggingFnT | None`**: Receives log messages sent from the server (`ctx.info`, `ctx.error`, etc.).
|
|
```python
|
|
from mcp.client.session import LoggingFnT, LogLevel
|
|
|
|
def my_log_handler(level: LogLevel, message: str, logger_name: str | None):
|
|
print(f"[Server Log - {level.upper()}] {logger_name or 'default'}: {message}")
|
|
|
|
client_with_logging = Client(
|
|
"my_server.py",
|
|
log_handler=my_log_handler
|
|
)
|
|
```
|
|
|
|
### Utility Methods
|
|
|
|
* **`ping()`**: Sends a ping request to the server to verify connectivity.
|
|
```python
|
|
async def check_connection():
|
|
async with client:
|
|
await client.ping()
|
|
print("Server is reachable")
|
|
```
|
|
|
|
### Error Handling
|
|
|
|
When a `call_tool` request results in an error on the server (e.g., the tool function raised an exception), the `client.call_tool()` method will raise a `fastmcp.client.ClientError`.
|
|
|
|
```python
|
|
async def safe_call_tool():
|
|
async with client:
|
|
try:
|
|
# Assume 'divide' tool exists and might raise ZeroDivisionError
|
|
result = await client.call_tool("divide", {"a": 10, "b": 0})
|
|
print(f"Result: {result}")
|
|
except ClientError as e:
|
|
print(f"Tool call failed: {e}")
|
|
except ConnectionError as e:
|
|
print(f"Connection failed: {e}")
|
|
except Exception as e:
|
|
print(f"An unexpected error occurred: {e}")
|
|
|
|
# Example Output if division by zero occurs:
|
|
# Tool call failed: Division by zero is not allowed.
|
|
```
|
|
|
|
Other errors, like connection failures, will raise standard Python exceptions (e.g., `ConnectionError`, `TimeoutError`).
|
|
|
|
<Tip>
|
|
The client transport often has its own error-handling mechanisms, so you can not always trap errors like those raised by `call_tool` outside of the `async with` block. Instead, you can call `call_tool(..., _return_raw_result=True)` to get the raw `mcp.types.CallToolResult` object and handle errors yourself by checking its `isError` attribute.
|
|
</Tip>
|