Add sampling docs, tools error handling, and SSE server example

- New docs/concepts/sampling/sampling.md covering server-side SampleAsync
  and AsSamplingChatClient, client-side CreateSamplingHandler and custom
  SamplingHandler delegate, and capability negotiation
- Add error handling section to docs/concepts/tools/tools.md with examples
  for automatic exception handling, McpProtocolException, and client-side
  IsError checking
- Add SSE server code example to docs/concepts/transports/transports.md
- Add sampling link to docs/concepts/index.md

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: jeffhandley

docs/concepts/index.md

@@ -19,6 +19,7 @@ Welcome to the conceptual documentation for the Model Context Protocol SDK. Here
 
 | Title | Description |
 | - | - |
+| [Sampling](sampling/sampling.md) | Learn how servers request LLM completions from the client using the sampling feature. |
 | [Roots](roots/roots.md) | Learn how clients provide filesystem roots to servers for context-aware operations. |
 | [Elicitation](elicitation/elicitation.md) | Learn how to request additional information from users during interactions. |
 

docs/concepts/sampling/sampling.md

@@ -0,0 +1,122 @@
+---
+title: Sampling
+author: jeffhandley
+description: How servers request LLM completions from the client using the sampling feature.
+uid: sampling
+---
+
+## Sampling
+
+MCP [sampling] allows servers to request LLM completions from the client. This enables agentic behaviors where a server-side tool delegates reasoning back to the client's language model — for example, summarizing content, generating text, or making decisions.
+
+[sampling]: https://modelcontextprotocol.io/specification/2025-11-25/client/sampling
+
+### How sampling works
+
+1. The server calls <xref:ModelContextProtocol.Server.McpServer.SampleAsync*> (or uses the <xref:ModelContextProtocol.Server.McpServer.AsSamplingChatClient*> adapter) during tool execution.
+2. The request is sent to the connected client over MCP.
+3. The client's <xref:ModelContextProtocol.Client.McpClientHandlers.SamplingHandler> processes the request — typically by forwarding it to an LLM.
+4. The client returns the LLM response to the server, which continues tool execution.
+
+### Server: requesting a completion
+
+Inject <xref:ModelContextProtocol.Server.McpServer> into a tool method and use the <xref:ModelContextProtocol.Server.McpServer.AsSamplingChatClient*> extension method to get an <xref:Microsoft.Extensions.AI.IChatClient> that sends requests through the connected client:
+
+```csharp
+[McpServerTool(Name = "SummarizeContent"), Description("Summarizes the given text")]
+public static async Task<string> Summarize(
+    McpServer server,
+    [Description("The text to summarize")] string text,
+    CancellationToken cancellationToken)
+{
+    ChatMessage[] messages =
+    [
+        new(ChatRole.User, "Briefly summarize the following content:"),
+        new(ChatRole.User, text),
+    ];
+
+    ChatOptions options = new()
+    {
+        MaxOutputTokens = 256,
+        Temperature = 0.3f,
+    };
+
+    return $"Summary: {await server.AsSamplingChatClient().GetResponseAsync(messages, options, cancellationToken)}";
+}
+```
+
+Alternatively, use <xref:ModelContextProtocol.Server.McpServer.SampleAsync*> directly for lower-level control:
+
+```csharp
+CreateMessageResult result = await server.SampleAsync(
+    new CreateMessageRequestParams
+    {
+        Messages =
+        [
+            new SamplingMessage
+            {
+                Role = Role.User,
+                Content = [new TextContentBlock { Text = "What is 2 + 2?" }]
+            }
+        ],
+        MaxTokens = 100,
+    },
+    cancellationToken);
+
+string response = result.Content.OfType<TextContentBlock>().FirstOrDefault()?.Text ?? string.Empty;
+```
+
+### Client: handling sampling requests
+
+Set <xref:ModelContextProtocol.Client.McpClientHandlers.SamplingHandler> when creating the client. This handler is called when a server sends a `sampling/createMessage` request.
+
+#### Using an IChatClient
+
+The simplest approach is to use <xref:ModelContextProtocol.AIContentExtensions.CreateSamplingHandler*> with any <xref:Microsoft.Extensions.AI.IChatClient> implementation:
+
+```csharp
+IChatClient chatClient = new OllamaChatClient(new Uri("http://localhost:11434"), "llama3");
+
+McpClientOptions options = new()
+{
+    Handlers = new()
+    {
+        SamplingHandler = chatClient.CreateSamplingHandler()
+    }
+};
+
+await using var client = await McpClient.CreateAsync(transport, options);
+```
+
+#### Custom handler
+
+For full control, provide a custom delegate:
+
+```csharp
+McpClientOptions options = new()
+{
+    Handlers = new()
+    {
+        SamplingHandler = async (request, progress, cancellationToken) =>
+        {
+            // Forward to your LLM, apply content filtering, etc.
+            string prompt = request?.Messages?.LastOrDefault()?.Content switch
+            {
+                TextContentBlock text => text.Text,
+                _ => string.Empty
+            };
+
+            return new CreateMessageResult
+            {
+                Model = "my-model",
+                Role = Role.Assistant,
+                Content = [new TextContentBlock { Text = $"Response to: {prompt}" }]
+            };
+        }
+    }
+};
+```
+
+### Capability negotiation
+
+Sampling requires the client to advertise the `sampling` capability. This is handled automatically — when a <xref:ModelContextProtocol.Client.McpClientHandlers.SamplingHandler> is set, the client includes the sampling capability during initialization. The server can check whether the client supports sampling before calling <xref:ModelContextProtocol.Server.McpServer.SampleAsync*>; if sampling is not supported, the method throws <xref:System.InvalidOperationException>.

docs/concepts/tools/tools.md

@@ -189,6 +189,66 @@ foreach (var content in result.Content)
 }
 ```
 
+### Error handling
+
+Tool errors in MCP are distinct from protocol errors. When a tool encounters an error during execution, the error is reported inside the <xref:ModelContextProtocol.Protocol.CallToolResult> with <xref:ModelContextProtocol.Protocol.CallToolResult.IsError> set to `true`, rather than as a protocol-level exception. This allows the LLM to see the error and potentially recover.
+
+#### Automatic exception handling
+
+When a tool method throws an exception, the server automatically catches it and returns a `CallToolResult` with `IsError = true`. <xref:ModelContextProtocol.McpProtocolException> is re-thrown as a JSON-RPC error, and <xref:System.OperationCanceledException> is re-thrown when the cancellation token was triggered. All other exceptions are returned as tool error results. For <xref:ModelContextProtocol.McpException> subclasses, the exception message is included in the error text; for other exceptions, a generic message is returned to avoid leaking internal details.
+
+```csharp
+[McpServerTool, Description("Divides two numbers")]
+public static double Divide(double a, double b)
+{
+    if (b == 0)
+    {
+        // ArgumentException is not an McpException, so the client receives a generic message:
+        // "An error occurred invoking 'divide'."
+        throw new ArgumentException("Cannot divide by zero");
+    }
+
+    return a / b;
+}
+```
+
+#### Protocol errors
+
+Throw <xref:ModelContextProtocol.McpProtocolException> to signal a protocol-level error (e.g., invalid parameters or unknown tool). These exceptions propagate as JSON-RPC error responses rather than tool error results:
+
+```csharp
+[McpServerTool, Description("Processes the input")]
+public static string Process(string input)
+{
+    if (string.IsNullOrEmpty(input))
+    {
+        // Propagates as a JSON-RPC error with code -32602 (InvalidParams)
+        // and message "Missing required input"
+        throw new McpProtocolException("Missing required input", McpErrorCode.InvalidParams);
+    }
+
+    return $"Processed: {input}";
+}
+```
+
+#### Checking for errors on the client
+
+On the client side, inspect the <xref:ModelContextProtocol.Protocol.CallToolResult.IsError> property after calling a tool:
+
+```csharp
+CallToolResult result = await client.CallToolAsync("divide", new Dictionary<string, object?>
+{
+    ["a"] = 10,
+    ["b"] = 0
+});
+
+if (result.IsError is true)
+{
+    // Prints: "Tool error: An error occurred invoking 'divide'."
+    Console.WriteLine($"Tool error: {result.Content.OfType<TextContentBlock>().FirstOrDefault()?.Text}");
+}
+```
+
 ### Tool list change notifications
 
 Servers can dynamically add, remove, or modify tools at runtime. When the tool list changes, the server notifies connected clients so they can refresh their tool list.

docs/concepts/transports/transports.md

@@ -160,7 +160,21 @@ SSE-specific configuration options:
 
 #### SSE server (ASP.NET Core)
 
-The ASP.NET Core integration supports SSE transport alongside Streamable HTTP. The same `MapMcp()` endpoint handles both protocols.
+The ASP.NET Core integration supports SSE transport alongside Streamable HTTP. The same `MapMcp()` endpoint handles both protocols — clients connecting with SSE are automatically served using the legacy SSE mechanism:
+
+```csharp
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddMcpServer()
+    .WithHttpTransport()
+    .WithTools<MyTools>();
+
+var app = builder.Build();
+app.MapMcp(); // Handles both Streamable HTTP and SSE clients
+app.Run();
+```
+
+No additional configuration is needed. When a client connects using the SSE protocol, the server responds with an SSE stream for server-to-client messages and accepts client-to-server messages via a separate POST endpoint.
 
 ### Transport mode comparison