AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

dotnet-mcp-builder

Build Model Context Protocol (MCP) servers in C#/.NET against the current ModelContextProtocol 2.x NuGet packages. Helps with cases the model gets wrong without guidance — stale versions (0.x preview or 1.x-era defaults), the v2 stateless-by-default HTTP flip, the 2026-07-28 spec deprecations (roots/sampling/logging), MCP Apps and Tasks extension packages, elicitation URL mode, per-session HTTP wiring, OAuth and reverse-proxy deploy specifics, and debugging MapMcp / STDIO / Streamable-HTTP errors. Also covers STDIO and Streamable HTTP transports (SSE is deprecated), tools, prompts, resources, completions, and a basic .NET MCP client. Trigger when the user says or implies any .NET MCP server work: ModelContextProtocol, McpServerTool, MapMcp, WithStdioServerTransport, "MCP server in C#", "MCP tool in dotnet", "expose this as MCP", or names a primitive (prompt/resource/elicitation/MCP App) in a .NET context. Skip for MCP work in other languages.

Original source
github
License
MIT
Pinned revision
5269f7ea2d6c3a9bfda5ed878b6726cf509121fd

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read github--dotnet-mcp-builder at revision 5269f7ea2d6c3a9bfda5ed878b6726cf509121fd, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 14

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.