awesome-copilot/skills/dotnet-mcp-builder/references/sampling.md

Sampling

Deprecated in the 2026-07-28 spec. SDK 2.x marks the sampling APIs [Obsolete] (build warning MCP9005). They stay wire-compatible with down-level clients during the transition, but don't design new servers around sampling: for "the tool needs user/LLM input mid-execution", prefer the multi-round-trip input_required pattern; for "the server needs an LLM", call a model directly server-side. Keep this page for maintaining existing 1.x-era servers; suppress MCP9005 only as a documented transition measure.

Sampling lets a tool call the LLM through the client instead of bringing its own model. The server says "summarise this for me" and the client routes the request to whatever model the user has configured (Claude, GPT, local model, anything). Costs and rate limits live with the client, not the server.

When to use sampling

• The tool needs an LLM step (summarise, classify, draft, extract) and you don't want to ship/configure your own model in the server.
• You want to respect the user's model choice, key, and cost preferences.
• You're building a "meta" tool that orchestrates LLM work as part of its job (e.g. multi-step agents).

If you already have a deterministic algorithm, don't add a sampling call "for flavour" — it adds latency and cost.

Prerequisite: stateful transport

Like elicitation, sampling needs the server to call back to the client. STDIO works always; HTTP needs options.Stateless = false.

Recommended: IChatClient adapter

The cleanest API wraps the sampling channel as Microsoft.Extensions.AI.IChatClient, so you write code that looks like normal LLM-calling .NET:

using System.ComponentModel;
using Microsoft.Extensions.AI;
using ModelContextProtocol.Server;

[McpServerToolType]
public class SummaryTools
{
    [McpServerTool(Name = "SummarizeContent"), Description("Summarises arbitrary text using the client's LLM.")]
    public static async Task<string> Summarize(
        IMcpServer server,
        [Description("The text to summarize")] string text,
        CancellationToken cancellationToken)
    {
        ChatMessage[] messages =
        [
            new(ChatRole.User, "Briefly summarize the following content:"),
            new(ChatRole.User, text),
        ];

        var options = new ChatOptions
        {
            MaxOutputTokens = 256,
            Temperature = 0.3f,
        };

        var response = await server.AsSamplingChatClient()
            .GetResponseAsync(messages, options, cancellationToken);

        return $"Summary: {response}";
    }
}

Why this is nice:

• Same IChatClient API the rest of the .NET AI ecosystem uses.
• Works with Microsoft.Extensions.AI middleware (rate limiting, retries, telemetry, function calling).
• You can swap to a direct provider in tests by injecting a different IChatClient.

Lower-level: SampleAsync

When you need full control over the request shape:

using ModelContextProtocol.Protocol;

CreateMessageResult result = await server.SampleAsync(
    new CreateMessageRequestParams
    {
        Messages =
        [
            new SamplingMessage
            {
                Role = Role.User,
                Content = [new TextContentBlock { Text = "What is 2 + 2?" }]
            }
        ],
        MaxTokens = 100,
        Temperature = 0.0f,
        SystemPrompt = "You are a precise calculator.",
        // ModelPreferences, StopSequences, IncludeContext...
    },
    cancellationToken);

string answer = result.Content
    .OfType<TextContentBlock>()
    .FirstOrDefault()?.Text ?? string.Empty;

ModelPreferences lets you hint at model selection (cost vs. speed vs. intelligence priority); the client decides the actual model.

ModelPreferences = new ModelPreferences
{
    Hints = [new ModelHint { Name = "claude" }],   // soft preference
    CostPriority = 0.2,        // 0..1
    SpeedPriority = 0.4,
    IntelligencePriority = 0.9,
}

IncludeContext

Sampling requests can ask the client to include context from the current conversation:

IncludeContext = ContextInclusion.ThisServer   // include this server's prior messages
// or AllServers, or None (default)

Useful when you need the LLM to consider what's happened in the chat so far without you re-supplying it.

Capability check

Always confirm the client supports sampling — many do not:

if (server.ClientCapabilities?.Sampling is null)
    throw new McpException(
        "This client does not support sampling. " +
        "Configure a model in the host or use a different MCP client.");

Performance notes

• Sampling calls are network round-trips (client → its provider → back). Expect 100ms–multiple seconds. Don't loop tightly.
• Token costs are paid by the user (their API key/quota). Be conservative with MaxTokens.
• Cancellation propagates: if the user kills the tool call, the sampling request is cancelled too.

Sampling vs. doing it server-side

Sampling (via client)	Direct LLM call (server-side)
Uses the user's model + key	Uses your service's key
Respects user's policy/quota	Your responsibility to bill/track
Works in any host the user has	Locked to the model you ship with
Higher latency (extra hop)	Lower latency, direct
No secrets to manage	You manage the API key

For "smart" servers shipped to many users, prefer sampling. For internal corporate servers where you want consistent behaviour and you're already paying for the model, direct is fine.