fastmcp 2.1.0__tar.gz → 2.1.1__tar.gz

{fastmcp-2.1.0 → fastmcp-2.1.1}/.github/workflows/run-tests.yml

@@ -32,7 +32,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        os: [ubuntu-latest, windows-latest, macos-latest]
+        os: [ubuntu-latest, windows-latest]
         python-version: ["3.10"]
       fail-fast: false
     timeout-minutes: 5

{fastmcp-2.1.0 → fastmcp-2.1.1}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: fastmcp
-Version: 2.1.0
-Summary: An ergonomic MCP interface
+Version: 2.1.1
+Summary: The fast, Pythonic way to build MCP servers.
 Author: Jeremiah Lowin
 License: Apache-2.0
 License-File: LICENSE
@@ -19,15 +19,16 @@ Description-Content-Type: text/markdown
 
 <!-- omit in toc -->
 # FastMCP v2 🚀
-<strong>The fast, Pythonic way to build MCP servers.</strong>
+<strong>The fast, Pythonic way to build MCP servers and clients.</strong>
 
+[![Docs](https://img.shields.io/badge/docs-gofastmcp.com-blue)](https://gofastmcp.com)
 [![PyPI - Version](https://img.shields.io/pypi/v/fastmcp.svg)](https://pypi.org/project/fastmcp)
 [![Tests](https://github.com/jlowin/fastmcp/actions/workflows/run-tests.yml/badge.svg)](https://github.com/jlowin/fastmcp/actions/workflows/run-tests.yml)
 [![License](https://img.shields.io/github/license/jlowin/fastmcp.svg)](https://github.com/jlowin/fastmcp/blob/main/LICENSE)
 
 </div>
 
-[Model Context Protocol (MCP)](https://modelcontextprotocol.io) servers are a standardized way to provide context and tools to your LLMs, and FastMCP makes building *and interacting with* them simple and intuitive. Create tools, expose resources, define prompts, and connect components with clean, Pythonic code.
+The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) is a new, standardized way to provide context and tools to your LLMs, and FastMCP makes building MCP servers and clients simple and intuitive. Create tools, expose resources, define prompts, and connect components with clean, Pythonic code.
 
 ```python
 # server.py
@@ -44,48 +45,27 @@ if __name__ == "__main__":
     mcp.run()
 ```
 
-Run it locally for testing:
-```bash
-fastmcp dev server.py
-```
 
-Install it for use with Claude Desktop:
+Run the server locally:
 ```bash
-fastmcp install server.py
+fastmcp run server.py
 ```
 
 FastMCP handles the complex protocol details and server management, letting you focus on building great tools and applications. It's designed to feel natural to Python developers.
 
-## Key Features:
-
-*   **Simple Server Creation:** Build MCP servers with minimal boilerplate using intuitive decorators (`@tool`, `@resource`, `@prompt`).
-*   **Proxy MCP Servers:** Create proxy servers to expose existing MCP servers or clients with modifications, or convert between transport protocols (e.g., expose a Stdio server via SSE for web access).
-*   **Compose MCP Servers:** Compose complex applications by mounting multiple FastMCP servers together.
-*   **API Generation:** Automatically create MCP servers from existing **OpenAPI specifications** or **FastAPI applications**.
-*   **Powerful Clients:** Programmatically interact with *any* MCP server, regardless of how it was built.
-*   **LLM Sampling:** Request completions from client LLMs directly within your MCP tools.
-*   **Pythonic Interface:** Designed with familiar Python patterns like decorators and type hints.
-*   **Context Injection:** Easily access core MCP capabilities like sampling, logging, and progress reporting within your functions.
-
----
-
-### What's New in v2?
-
-FastMCP 1.0 made it so easy to build MCP servers that it's now part of the [official Model Context Protocol Python SDK](https://github.com/modelcontextprotocol/python-sdk)! For basic use cases, you can use the upstream version by importing `mcp.server.fastmcp.FastMCP` (or installing `fastmcp=1.0`). 
-
-Based on how the MCP ecosystem is evolving, FastMCP 2.0 builds on that foundation to introduce a variety of new features (and more experimental ideas). It adds advanced features like proxying and composing MCP servers, as well as automatically generating them from OpenAPI specs or FastAPI objects. FastMCP 2.0 also introduces new client-side functionality like LLM sampling.
-
-
----
 
 <!-- omit in toc -->
 ## Table of Contents
 
-- [Key Features:](#key-features)
-  - [What's New in v2?](#whats-new-in-v2)
-- [Installation](#installation)
-- [Quickstart](#quickstart)
 - [What is MCP?](#what-is-mcp)
+- [Why FastMCP?](#why-fastmcp)
+- [Key Features](#key-features)
+  - [Servers](#servers)
+  - [Clients](#clients)
+- [What's New in v2?](#whats-new-in-v2)
+- [Documentation](#documentation)
+  - [Installation](#installation)
+  - [Quickstart](#quickstart)
 - [Core Concepts](#core-concepts)
   - [The `FastMCP` Server](#the-fastmcp-server)
   - [Tools](#tools)
@@ -115,7 +95,62 @@ Based on how the MCP ecosystem is evolving, FastMCP 2.0 builds on that foundatio
     - [Formatting \& Linting](#formatting--linting)
     - [Pull Requests](#pull-requests)
 
-## Installation
+
+## What is MCP?
+
+The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) lets you build servers that expose data and functionality to LLM applications in a secure, standardized way. Think of it like a web API, but specifically designed for LLM interactions. MCP servers can:
+
+- Expose data through **Resources** (think GET endpoints; load info into context)
+- Provide functionality through **Tools** (think POST/PUT endpoints; execute actions)
+- Define interaction patterns through **Prompts** (reusable templates)
+- And more!
+
+FastMCP provides a high-level, Pythonic interface for building and interacting with these servers.
+
+## Why FastMCP?
+
+The MCP protocol is powerful but implementing it involves a lot of boilerplate - server setup, protocol handlers, content types, error management. FastMCP handles all the complex protocol details and server management, so you can focus on building great tools. It’s designed to be high-level and Pythonic; in most cases, decorating a function is all you need.
+
+FastMCP aims to be:
+
+
+🚀 **Fast:** High-level interface means less code and faster development
+
+🍀 **Simple:** Build MCP servers with minimal boilerplate
+
+🐍 **Pythonic:** Feels natural to Python developers
+
+🔍 **Complete:** FastMCP aims to provide a full implementation of the core MCP specification for both servers and clients
+
+## Key Features
+
+### Servers
+- **Create** servers with minimal boilerplate using intuitive decorators
+- **Proxy** existing servers to modify configuration or transport
+- **Compose** servers by into complex applications
+- **Generate** servers from OpenAPI specs or FastAPI objects
+
+### Clients
+- **Interact** with MCP servers programmatically
+- **Connect** to any MCP server using any transport
+- **Test** your servers without manual intervention
+- **Innovate** with core MCP capabilities like LLM sampling
+
+
+## What's New in v2?
+
+FastMCP 1.0 made it so easy to build MCP servers that it's now part of the [official Model Context Protocol Python SDK](https://github.com/modelcontextprotocol/python-sdk)! For basic use cases, you can use the upstream version by importing `mcp.server.fastmcp.FastMCP` (or installing `fastmcp=1.0`). 
+
+Based on how the MCP ecosystem is evolving, FastMCP 2.0 builds on that foundation to introduce a variety of new features (and more experimental ideas). It adds advanced features like proxying and composing MCP servers, as well as automatically generating them from OpenAPI specs or FastAPI objects. FastMCP 2.0 also introduces new client-side functionality like LLM sampling.
+
+
+## Documentation
+
+📚 FastMCP's documentation is available at [gofastmcp.com](https://gofastmcp.com).
+
+---
+
+### Installation
 
 We strongly recommend installing FastMCP with [uv](https://docs.astral.sh/uv/), as it is required for deploying servers via the CLI:
 
@@ -134,7 +169,7 @@ cd fastmcp
 uv sync
 ```
 
-## Quickstart
+### Quickstart
 
 Let's create a simple MCP server that exposes a calculator tool and some data:
 
@@ -163,23 +198,8 @@ You can install this server in [Claude Desktop](https://claude.ai/download) and
 fastmcp install server.py
 ```
 
-Alternatively, you can test it with the MCP Inspector:
-```bash
-fastmcp dev server.py
-```
-
 ![MCP Inspector](/docs/assets/demo-inspector.png)
 
-## What is MCP?
-
-The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) lets you build servers that expose data and functionality to LLM applications in a secure, standardized way. Think of it like a web API, but specifically designed for LLM interactions. MCP servers can:
-
-- Expose data through **Resources** (think GET endpoints; load info into context)
-- Provide functionality through **Tools** (think POST/PUT endpoints; execute actions)
-- Define interaction patterns through **Prompts** (reusable templates)
-- And more!
-
-FastMCP provides a high-level, Pythonic interface for building and interacting with these servers.
 
 ## Core Concepts
 

{fastmcp-2.1.0 → fastmcp-2.1.1}/README.md

@@ -2,15 +2,16 @@
 
 <!-- omit in toc -->
 # FastMCP v2 🚀
-<strong>The fast, Pythonic way to build MCP servers.</strong>
+<strong>The fast, Pythonic way to build MCP servers and clients.</strong>
 
+[![Docs](https://img.shields.io/badge/docs-gofastmcp.com-blue)](https://gofastmcp.com)
 [![PyPI - Version](https://img.shields.io/pypi/v/fastmcp.svg)](https://pypi.org/project/fastmcp)
 [![Tests](https://github.com/jlowin/fastmcp/actions/workflows/run-tests.yml/badge.svg)](https://github.com/jlowin/fastmcp/actions/workflows/run-tests.yml)
 [![License](https://img.shields.io/github/license/jlowin/fastmcp.svg)](https://github.com/jlowin/fastmcp/blob/main/LICENSE)
 
 </div>
 
-[Model Context Protocol (MCP)](https://modelcontextprotocol.io) servers are a standardized way to provide context and tools to your LLMs, and FastMCP makes building *and interacting with* them simple and intuitive. Create tools, expose resources, define prompts, and connect components with clean, Pythonic code.
+The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) is a new, standardized way to provide context and tools to your LLMs, and FastMCP makes building MCP servers and clients simple and intuitive. Create tools, expose resources, define prompts, and connect components with clean, Pythonic code.
 
 ```python
 # server.py
@@ -27,48 +28,27 @@ if __name__ == "__main__":
     mcp.run()
 ```
 
-Run it locally for testing:
-```bash
-fastmcp dev server.py
-```
 
-Install it for use with Claude Desktop:
+Run the server locally:
 ```bash
-fastmcp install server.py
+fastmcp run server.py
 ```
 
 FastMCP handles the complex protocol details and server management, letting you focus on building great tools and applications. It's designed to feel natural to Python developers.
 
-## Key Features:
-
-*   **Simple Server Creation:** Build MCP servers with minimal boilerplate using intuitive decorators (`@tool`, `@resource`, `@prompt`).
-*   **Proxy MCP Servers:** Create proxy servers to expose existing MCP servers or clients with modifications, or convert between transport protocols (e.g., expose a Stdio server via SSE for web access).
-*   **Compose MCP Servers:** Compose complex applications by mounting multiple FastMCP servers together.
-*   **API Generation:** Automatically create MCP servers from existing **OpenAPI specifications** or **FastAPI applications**.
-*   **Powerful Clients:** Programmatically interact with *any* MCP server, regardless of how it was built.
-*   **LLM Sampling:** Request completions from client LLMs directly within your MCP tools.
-*   **Pythonic Interface:** Designed with familiar Python patterns like decorators and type hints.
-*   **Context Injection:** Easily access core MCP capabilities like sampling, logging, and progress reporting within your functions.
-
----
-
-### What's New in v2?
-
-FastMCP 1.0 made it so easy to build MCP servers that it's now part of the [official Model Context Protocol Python SDK](https://github.com/modelcontextprotocol/python-sdk)! For basic use cases, you can use the upstream version by importing `mcp.server.fastmcp.FastMCP` (or installing `fastmcp=1.0`). 
-
-Based on how the MCP ecosystem is evolving, FastMCP 2.0 builds on that foundation to introduce a variety of new features (and more experimental ideas). It adds advanced features like proxying and composing MCP servers, as well as automatically generating them from OpenAPI specs or FastAPI objects. FastMCP 2.0 also introduces new client-side functionality like LLM sampling.
-
-
----
 
 <!-- omit in toc -->
 ## Table of Contents
 
-- [Key Features:](#key-features)
-  - [What's New in v2?](#whats-new-in-v2)
-- [Installation](#installation)
-- [Quickstart](#quickstart)
 - [What is MCP?](#what-is-mcp)
+- [Why FastMCP?](#why-fastmcp)
+- [Key Features](#key-features)
+  - [Servers](#servers)
+  - [Clients](#clients)
+- [What's New in v2?](#whats-new-in-v2)
+- [Documentation](#documentation)
+  - [Installation](#installation)
+  - [Quickstart](#quickstart)
 - [Core Concepts](#core-concepts)
   - [The `FastMCP` Server](#the-fastmcp-server)
   - [Tools](#tools)
@@ -98,7 +78,62 @@ Based on how the MCP ecosystem is evolving, FastMCP 2.0 builds on that foundatio
     - [Formatting \& Linting](#formatting--linting)
     - [Pull Requests](#pull-requests)
 
-## Installation
+
+## What is MCP?
+
+The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) lets you build servers that expose data and functionality to LLM applications in a secure, standardized way. Think of it like a web API, but specifically designed for LLM interactions. MCP servers can:
+
+- Expose data through **Resources** (think GET endpoints; load info into context)
+- Provide functionality through **Tools** (think POST/PUT endpoints; execute actions)
+- Define interaction patterns through **Prompts** (reusable templates)
+- And more!
+
+FastMCP provides a high-level, Pythonic interface for building and interacting with these servers.
+
+## Why FastMCP?
+
+The MCP protocol is powerful but implementing it involves a lot of boilerplate - server setup, protocol handlers, content types, error management. FastMCP handles all the complex protocol details and server management, so you can focus on building great tools. It’s designed to be high-level and Pythonic; in most cases, decorating a function is all you need.
+
+FastMCP aims to be:
+
+
+🚀 **Fast:** High-level interface means less code and faster development
+
+🍀 **Simple:** Build MCP servers with minimal boilerplate
+
+🐍 **Pythonic:** Feels natural to Python developers
+
+🔍 **Complete:** FastMCP aims to provide a full implementation of the core MCP specification for both servers and clients
+
+## Key Features
+
+### Servers
+- **Create** servers with minimal boilerplate using intuitive decorators
+- **Proxy** existing servers to modify configuration or transport
+- **Compose** servers by into complex applications
+- **Generate** servers from OpenAPI specs or FastAPI objects
+
+### Clients
+- **Interact** with MCP servers programmatically
+- **Connect** to any MCP server using any transport
+- **Test** your servers without manual intervention
+- **Innovate** with core MCP capabilities like LLM sampling
+
+
+## What's New in v2?
+
+FastMCP 1.0 made it so easy to build MCP servers that it's now part of the [official Model Context Protocol Python SDK](https://github.com/modelcontextprotocol/python-sdk)! For basic use cases, you can use the upstream version by importing `mcp.server.fastmcp.FastMCP` (or installing `fastmcp=1.0`). 
+
+Based on how the MCP ecosystem is evolving, FastMCP 2.0 builds on that foundation to introduce a variety of new features (and more experimental ideas). It adds advanced features like proxying and composing MCP servers, as well as automatically generating them from OpenAPI specs or FastAPI objects. FastMCP 2.0 also introduces new client-side functionality like LLM sampling.
+
+
+## Documentation
+
+📚 FastMCP's documentation is available at [gofastmcp.com](https://gofastmcp.com).
+
+---
+
+### Installation
 
 We strongly recommend installing FastMCP with [uv](https://docs.astral.sh/uv/), as it is required for deploying servers via the CLI:
 
@@ -117,7 +152,7 @@ cd fastmcp
 uv sync
 ```
 
-## Quickstart
+### Quickstart
 
 Let's create a simple MCP server that exposes a calculator tool and some data:
 
@@ -146,23 +181,8 @@ You can install this server in [Claude Desktop](https://claude.ai/download) and
 fastmcp install server.py
 ```
 
-Alternatively, you can test it with the MCP Inspector:
-```bash
-fastmcp dev server.py
-```
-
 ![MCP Inspector](/docs/assets/demo-inspector.png)
 
-## What is MCP?
-
-The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) lets you build servers that expose data and functionality to LLM applications in a secure, standardized way. Think of it like a web API, but specifically designed for LLM interactions. MCP servers can:
-
-- Expose data through **Resources** (think GET endpoints; load info into context)
-- Provide functionality through **Tools** (think POST/PUT endpoints; execute actions)
-- Define interaction patterns through **Prompts** (reusable templates)
-- And more!
-
-FastMCP provides a high-level, Pythonic interface for building and interacting with these servers.
 
 ## Core Concepts
 

fastmcp-2.1.1/docs/clients/overview.mdx

@@ -0,0 +1,252 @@
+---
+title: Client Overview
+sidebarTitle: Overview
+description: Learn how to use the FastMCP Client to interact with MCP servers.
+icon: user-robot
+---
+
+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
+    )
+    ```
+
+
+### 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_tools(..., return_raw_result=True)` to get the raw result object and handle errors yourself by checking its `isError` attribute.
+</Tip>