Skip to content

Docs edit pass #1451

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
gewarren wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Docs edit pass #1451

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
51a8615
edit pass
gewarren Mar 20, 2026
41b5fac
reverts
gewarren Mar 20, 2026
4dd705b
Apply suggestion from @gewarren
gewarren Mar 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions docs/concepts/cancellation/cancellation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,18 +7,18 @@ uid: cancellation

## Cancellation

MCP supports [cancellation] of in-flight requests. Either side can cancel a previously issued request, and `CancellationToken` parameters on MCP methods are wired to send and receive `notifications/cancelled` notifications over the protocol.
MCP supports [cancellation] of in-flight requests. Either side can cancel a previously issued request, and <xref:System.Threading.CancellationToken> parameters on MCP methods are wired to send and receive `notifications/cancelled` notifications over the protocol.

[cancellation]: https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/cancellation
[task cancellation]: https://learn.microsoft.com/dotnet/standard/parallel-programming/task-cancellation

### How cancellation maps to MCP notifications

When a `CancellationToken` passed to a client method (such as <xref:ModelContextProtocol.Client.McpClient.CallToolAsync*>) is cancelled, a `notifications/cancelled` notification is sent to the server with the request ID. On the server side, the `CancellationToken` provided to the tool method is then triggered, allowing the handler to stop work gracefully. This same mechanism works in reverse for server-to-client requests.
When a <xref:System.Threading.CancellationToken> passed to a client method (such as <xref:ModelContextProtocol.Client.McpClient.CallToolAsync*>) is cancelled, a `notifications/cancelled` notification is sent to the server with the request ID. On the server side, the <xref:System.Threading.CancellationToken> provided to the tool method is then triggered, allowing the handler to stop work gracefully. This same mechanism works in reverse for server-to-client requests.

### Server-side cancellation handling

Server tool methods receive a `CancellationToken` that is triggered when the client sends a cancellation notification. Pass this token through to any async operations so they stop promptly:
Server tool methods receive a <xref:System.Threading.CancellationToken> that is triggered when the client sends a cancellation notification. Pass this token through to any async operations so they stop promptly:

```csharp
[McpServerTool, Description("A long-running computation")]
Expand All @@ -35,7 +35,7 @@ public static async Task<string> LongComputation(
}
```

When the client sends a cancellation notification, the `OperationCanceledException` propagates back to the client as a cancellation response.
When the client sends a cancellation notification, the <xref:System.OperationCanceledException> propagates back to the client as a cancellation response.

### Cancellation notification details

Expand Down
38 changes: 19 additions & 19 deletions docs/concepts/capabilities/capabilities.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,11 +15,11 @@ MCP uses a [capability negotiation] mechanism during connection setup. Clients a

<xref:ModelContextProtocol.Protocol.ClientCapabilities> declares what features the client supports:

| Capability | Type | Description |
|-----------|------|-------------|
| `Roots` | <xref:ModelContextProtocol.Protocol.RootsCapability> | Client can provide filesystem root URIs |
| `Sampling` | <xref:ModelContextProtocol.Protocol.SamplingCapability> | Client can handle LLM sampling requests |
| `Elicitation` | <xref:ModelContextProtocol.Protocol.ElicitationCapability> | Client can present forms or URLs to the user |
| Capability | Type | Description |
|----------------|-------------------------------|---------------------------|
| `Roots` | <xref:ModelContextProtocol.Protocol.RootsCapability> | Client can provide filesystem root URIs |
| `Sampling` | <xref:ModelContextProtocol.Protocol.SamplingCapability> | Client can handle LLM sampling requests |
| `Elicitation` | <xref:ModelContextProtocol.Protocol.ElicitationCapability> | Client can present forms or URLs to the user |
| `Experimental` | `IDictionary<string, object>` | Experimental capabilities |

Configure client capabilities when creating an MCP client:
Expand Down Expand Up @@ -48,13 +48,13 @@ Handlers for each capability (roots, sampling, elicitation) are covered in their

<xref:ModelContextProtocol.Protocol.ServerCapabilities> declares what features the server supports:

| Capability | Type | Description |
|-----------|------|-------------|
| `Tools` | <xref:ModelContextProtocol.Protocol.ToolsCapability> | Server exposes callable tools |
| `Prompts` | <xref:ModelContextProtocol.Protocol.PromptsCapability> | Server exposes prompt templates |
| `Resources` | <xref:ModelContextProtocol.Protocol.ResourcesCapability> | Server exposes readable resources |
| `Logging` | <xref:ModelContextProtocol.Protocol.LoggingCapability> | Server can send log messages |
| `Completions` | <xref:ModelContextProtocol.Protocol.CompletionsCapability> | Server supports argument completions |
| Capability | Type | Description |
|----------------|-------------------------------|---------------------------|
| `Tools` | <xref:ModelContextProtocol.Protocol.ToolsCapability> | Server exposes callable tools |
| `Prompts` | <xref:ModelContextProtocol.Protocol.PromptsCapability> | Server exposes prompt templates |
| `Resources` | <xref:ModelContextProtocol.Protocol.ResourcesCapability> | Server exposes readable resources |
| `Logging` | <xref:ModelContextProtocol.Protocol.LoggingCapability> | Server can send log messages |
| `Completions` | <xref:ModelContextProtocol.Protocol.CompletionsCapability> | Server supports argument completions |
| `Experimental` | `IDictionary<string, object>` | Experimental capabilities |

Server capabilities are automatically inferred from the configured features. For example, registering tools with `.WithTools<T>()` automatically declares the tools capability.
Expand All @@ -68,19 +68,19 @@ Before using an optional feature, check whether the other side declared the corr
```csharp
await using var client = await McpClient.CreateAsync(transport);

// Check if the server supports tools
// Check if the server supports tools.
if (client.ServerCapabilities.Tools is not null)
{
var tools = await client.ListToolsAsync();
}

// Check if the server supports resources with subscriptions
// Check if the server supports resources with subscriptions.
if (client.ServerCapabilities.Resources is { Subscribe: true })
{
await client.SubscribeToResourceAsync("config://app/settings");
}

// Check if the server supports prompts with list-changed notifications
// Check if the server supports prompts with list-changed notifications.
if (client.ServerCapabilities.Prompts is { ListChanged: true })
{
mcpClient.RegisterNotificationHandler(
Expand All @@ -91,13 +91,13 @@ if (client.ServerCapabilities.Prompts is { ListChanged: true })
});
}

// Check if the server supports logging
// Check if the server supports logging.
if (client.ServerCapabilities.Logging is not null)
{
await client.SetLoggingLevelAsync(LoggingLevel.Info);
}

// Check if the server supports completions
// Check if the server supports completions.
if (client.ServerCapabilities.Completions is not null)
{
var completions = await client.CompleteAsync(
Expand All @@ -112,10 +112,10 @@ if (client.ServerCapabilities.Completions is not null)
During connection setup, the client and server negotiate a mutually supported MCP protocol version. After initialization, the negotiated version is available on both sides:

```csharp
// On the client
// On the client.
string? version = client.NegotiatedProtocolVersion;

// On the server (within a tool or handler)
// On the server (within a tool or handler).
string? version = server.NegotiatedProtocolVersion;
```

Expand Down
18 changes: 9 additions & 9 deletions docs/concepts/completions/completions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,8 @@ MCP [completions] allow servers to provide argument auto-completion suggestions

Completions work with two types of references:

- **Prompt argument completions**: Suggest values for prompt parameters (e.g., language names, style options)
- **Resource template argument completions**: Suggest values for URI template parameters (e.g., file paths, resource IDs)
- **Prompt argument completions**: Suggest values for prompt parameters (for example, language names and style options).
- **Resource template argument completions**: Suggest values for URI template parameters (for example, file paths and resource IDs).

The server returns a <xref:ModelContextProtocol.Protocol.Completion> object containing a list of suggested values, an optional total count, and a flag indicating if more values are available.

Expand All @@ -36,7 +36,7 @@ builder.Services.AddMcpServer()

var argument = @params.Argument;

// Handle prompt argument completions
// Handle prompt argument completions.
if (@params.Ref is PromptReference promptRef)
{
var suggestions = argument.Name switch
Expand All @@ -46,7 +46,7 @@ builder.Services.AddMcpServer()
_ => Array.Empty<string>()
};

// Filter suggestions based on what the user has typed so far
// Filter suggestions based on what the user has typed so far.
var filtered = suggestions.Where(s => s.StartsWith(argument.Value, StringComparison.OrdinalIgnoreCase)).ToList();

return new CompleteResult
Expand All @@ -60,7 +60,7 @@ builder.Services.AddMcpServer()
};
}

// Handle resource template argument completions
// Handle resource template argument completions.
if (@params.Ref is ResourceTemplateReference resourceRef)
{
var availableIds = new[] { "1", "2", "3", "4", "5" };
Expand All @@ -83,7 +83,7 @@ builder.Services.AddMcpServer()

### Automatic completions with AllowedValuesAttribute

For parameters with a known set of valid values, you can use `System.ComponentModel.DataAnnotations.AllowedValuesAttribute` on `string` parameters of prompts or resource templates. The server will automatically surface those values as completions without needing a custom completion handler.
For parameters with a known set of valid values, you can use <xref:System.ComponentModel.DataAnnotations.AllowedValuesAttribute> on `string` parameters of prompts or resource templates. The server will automatically surface those values as completions without needing a custom completion handler.

#### Prompt parameters

Expand Down Expand Up @@ -124,13 +124,13 @@ Clients request completions using <xref:ModelContextProtocol.Client.McpClient.Co
#### Prompt argument completions

```csharp
// Get completions for a prompt argument
// Get completions for a prompt argument.
CompleteResult result = await client.CompleteAsync(
new PromptReference { Name = "code_review" },
argumentName: "language",
argumentValue: "type");

// result.Completion.Values might contain: ["typescript"]
// result.Completion.Values might contain: ["typescript"].
foreach (var suggestion in result.Completion.Values)
{
Console.WriteLine($" {suggestion}");
Expand All @@ -145,7 +145,7 @@ if (result.Completion.HasMore == true)
#### Resource template argument completions

```csharp
// Get completions for a resource template argument
// Get completions for a resource template argument.
CompleteResult result = await client.CompleteAsync(
new ResourceTemplateReference { Uri = "file:///{path}" },
argumentName: "path",
Expand Down
Loading
Loading