---
title: LLM Sampling
sidebarTitle: Sampling
description: Handle server-initiated LLM sampling requests.
icon: robot
---

import { VersionBadge } from '/snippets/version-badge.mdx'

<VersionBadge version="2.0.0" />

MCP servers can request LLM completions from clients. The client handles these requests through a sampling handler callback.

## Setting Up Sampling Handling

Provide a `sampling_handler` function when creating the client:

```python
from fastmcp import Client
from fastmcp.client.sampling import (
    SamplingMessage,
    SamplingParams,
    RequestContext,
)

async def sampling_handler(
    messages: list[SamplingMessage],
    params: SamplingParams,
    context: RequestContext
) -> str:
    # Your LLM integration logic here
    # Extract text from messages and generate a response
    return "Generated response based on the messages"

client = Client(
    "my_mcp_server.py",
    sampling_handler=sampling_handler,
)
```

## Handler Parameters

The sampling handler receives three parameters:

### SamplingMessage

- **`role`**: Message role (e.g., "user", "assistant", "system")
- **`content`**: Message content (usually has `.text` attribute)

### SamplingParams

- **`systemPrompt`**: System prompt string (optional)
- **`maxTokens`**: Maximum tokens to generate (optional)
- **`temperature`**: Sampling temperature (optional)
- **`topP`**: Top-p sampling parameter (optional)
- **`stopSequences`**: List of stop sequences (optional)

### RequestContext

- **`request_id`**: Unique identifier for the sampling request

## Basic Example

```python
from fastmcp import Client
from fastmcp.client.sampling import SamplingMessage, SamplingParams, RequestContext

async def basic_sampling_handler(
    messages: list[SamplingMessage],
    params: SamplingParams,
    context: RequestContext
) -> str:
    # Extract message content
    conversation = []
    for message in messages:
        content = message.content.text if hasattr(message.content, 'text') else str(message.content)
        conversation.append(f"{message.role}: {content}")
    
    # Use the system prompt if provided
    system_prompt = params.systemPrompt or "You are a helpful assistant."
    
    # Here you would integrate with your preferred LLM service
    # This is just a placeholder response
    return f"Response based on conversation: {' | '.join(conversation)}"

client = Client(
    "my_mcp_server.py",
    sampling_handler=basic_sampling_handler
)
```