microsoft/semantic-kernel · error · InvalidOperationException

The client does not support sampling.

Error message

The client does not support sampling.

What it means

Thrown by an MCP server tool when the connected client did not declare the 'sampling' capability during the MCP initialization handshake. MCP sampling lets a server ask the client to perform LLM inference on its behalf; if the client omitted sampling from its ClientCapabilities, the server cannot delegate and must abort. The guard exists because the SummarizeUnreadEmailsAsync tool relies entirely on client-side sampling to produce its summary.

Source

Thrown at dotnet/samples/Demos/ModelContextProtocolClientServer/MCPServer/Tools/MailboxUtils.cs:24

using ModelContextProtocol.Server;

namespace MCPServer.Tools;

/// <summary>
/// A collection of utility methods for working with mailbox.
/// </summary>
internal sealed class MailboxUtils
{
    /// <summary>
    /// Summarizes unread emails in the mailbox by using MCP sampling
    /// mechanism for summarization.
    /// </summary>
    [KernelFunction]
    public static async Task<string> SummarizeUnreadEmailsAsync([FromKernelServices] McpServer server)
    {
        if (server.ClientCapabilities?.Sampling is null)
        {
            throw new InvalidOperationException("The client does not support sampling.");
        }

        // Create two sample emails with attachments
        var email1 = new Email
        {
            Sender = "sales.report@example.com",
            Subject = "Carretera Sales Report - Jan & Jun 2014",
            Body = "Hi there, I hope this email finds you well! Please find attached the sales report for the first half of 2014. " +
                   "Please review the report and provide your feedback today, if possible." +
                   "By the way, we're having a BBQ this Saturday at my place, and you're welcome to join. Let me know if you can make it!",
            Attachments = [EmbeddedResource.ReadAsBytes("SalesReport2014.png")]
        };

        var email2 = new Email
        {
            Sender = "hr.department@example.com",
            Subject = "Employee Birthdays and Positions",
            Body = "Attached is the list of employee birthdays and their positions. Please check it and let me know of any updates by tomorrow." +

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Use an MCP client that declares sampling capability in its InitializeRequest (e.g., a Semantic Kernel McpClient configured with sampling enabled).
2. Verify the client's initialize handshake includes "capabilities": { "sampling": {} } before listing/calling the tool.
3. If you control the client, register a sampling handler so the server can round-trip its sampling request back to the client's LLM.
4. If sampling is unavailable, remove or bypass this tool and provide an alternative summarization path that runs server-side.

Example fix

// before
// Client connects with no capabilities → tool throws

// after — client declares sampling capability (Semantic Kernel MCP client)
var clientTransport = new StdioClientTransport(new("node", "server.js"));
await mcpClient.ConnectAsync(clientTransport);
// Ensure your MCP client advertises sampling:
//   clientOptions.Capabilities.Sampling = new SamplingCapability();
// and register a handler:
//   clientOptions.SamplingHandler = mySamplingHandler;

// Before invoking the tool, check client capabilities
if (server.ClientCapabilities?.Sampling is null)
{
    Console.WriteLine("Warning: client does not support sampling; skip SummarizeUnreadEmailsAsync.");
    return;
}

bool ClientSupportsSampling(McpServer server) => server.ClientCapabilities?.Sampling is not null;

When it happens

Trigger: Calling SummarizeUnreadEmailsAsync (a [KernelFunction] on MailboxUtils) when the MCP client connected without declaring Sampling in its capabilities — e.g., using a minimal MCP client that only advertises roots or tools, or a stdio transport client whose initialization message omitted the sampling capability object.

Common situations: Using a lightweight or custom MCP client SDK that doesn't enable sampling by default; connecting with the Claude Desktop client or another client that does not support sampling; testing the server with a raw MCP client that sends a capabilities object without a sampling field; version mismatch where the client SDK hasn't implemented sampling yet.

Related errors

• Request context is required for sampling function.
• Plugin creation failed for {pluginName}
• Prompt name is required.
• No handler found for the prompt '{promptName}'.
• Resource uri is required.

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/0d8a7a90fa137992. Report an issue: GitHub.