McpSdk.Shared 1.2.0

McpSdk

A lean C# SDK for the Model Context Protocol — build MCP clients and servers in .NET over stdio or Streamable HTTP. The core has zero third-party dependencies; JSON and logging are pluggable adapters you opt into. Targets netstandard2.0 and net10.0.

It implements the 2025-11-25 protocol revision and negotiates down to older peers (2025-06-18, 2025-03-26, 2024-11-05).

Features

• Servers and clients with a small, fluent builder API.
• Two transports — stdio and Streamable HTTP (single endpoint, sessions, SSE, Last-Event-ID resumption).
• Tools with JSON Schema 2020-12 input/output schemas, structured output, titles, annotations, and icons.
• Prompts, resources (with subscriptions), completion, and logging capabilities.
• Client-side sampling, roots, and elicitation for server→client requests.
• Pagination, progress, cancellation, and _meta passthrough throughout.
• Pluggable JSON — System.Text.Json or Newtonsoft.Json — and logging adapters.

Installation

The SDK is split into small packages so you only pull what you need. Pick Server or Client, add a JSON adapter, plus any transport/logging adapters. McpSdk.Protocol and McpSdk.Shared come in transitively.

# Build a server
dotnet add package McpSdk.Server
dotnet add package McpSdk.Adapter.System.Text.Json

# Build a client
dotnet add package McpSdk.Client
dotnet add package McpSdk.Adapter.System.Text.Json

Swapping JSON engines is a one-line change: use NewtonsoftJson from McpSdk.Adapter.Newtonsoft.Json anywhere SystemJson appears below — both implement IJson.

Quick start

Server

Expose a tool over stdio:

using McpSdk.Adapter.System.Text.Json;
using McpSdk.Server;

var json = new SystemJson();

var server = new ServerBuilder()
    .WithName("Demo Server")
    .WithVersion("1.0.0")
    .WithStdioTransport(json)
    .WithDefaultToolsCapability(json, tools => tools.AddTool(new EchoTool()))
    .Build();

await server.Start();

// A stdio client shuts a server down by closing its stdin: WaitForShutdown returns on that (or on
// the token you pass), and Stop drains the responses still in flight before the wire closes.
await server.WaitForShutdown();
await server.Stop();

A tool is any IToolHandler — it advertises a Tool (name, description, JSON Schema) and handles the call:

using McpSdk.Protocol;
using McpSdk.Protocol.Models;
using McpSdk.Server;

public sealed class EchoTool : IToolHandler
{
    public Tool Tool { get; } = new Tool(
        "echo",
        "Echoes back the text you send.",
        new ObjectSchema
        {
            { "text", new StringSchema { Description = "Text to echo back" } },
        });

    public Task<CallToolResult> Call(IJsonObject args, McpRequestContext context)
    {
        var text = args["text"].AsString();
        var result = new CallToolResult([new TextContent($"You said: {text}")], isError: false);
        return Task.FromResult(result);
    }
}

Client

Launch a server process and call its tools over stdio:

using McpSdk.Adapter.System.Text.Json;
using McpSdk.Client;
using McpSdk.Client.Transports;
using McpSdk.Protocol.Models;

var json = new SystemJson();

var client = new ClientBuilder()
    .WithName("Demo Client")
    .WithVersion("1.0.0")
    .WithStdioTransport(json, "dotnet", ["run", "--project", "DemoServer"])
    .Build();

await client.Connect();

var tools = await client.ListTools();
foreach (var tool in tools.Tools)
    Console.WriteLine(tool.Name);

var request = new CallToolRequest("echo", json.Parse(json.Stringify(props =>
{
    props.Write("text", "hello");
})));
var result = await client.CallTool(request);

Streamable HTTP

A single MCP endpoint over HTTP. The listener issues an Mcp-Session-Id on initialize and serves one server per session; subsequent requests carry that id and the MCP-Protocol-Version header. Disallowed Origins are rejected with 403, and the server→client GET stream supports Last-Event-ID resumption.

// Server
using McpSdk.Adapter.ConsoleLogger;
using McpSdk.Adapter.StreamableHttpServer;
using McpSdk.Adapter.System.Text.Json;
using McpSdk.Server;

var json = new SystemJson();
var loggerFactory = new ServerConsoleLoggerFactory();

var listener = new StreamableHttpListener(
    "http://localhost:3000", "/mcp", json, loggerFactory,
    onSession: async transport =>
    {
        var server = new ServerBuilder()
            .WithName("Demo Server")
            .WithVersion("1.0.0")
            .WithLogger(loggerFactory)
            .WithStreamableHttpTransport(transport)
            .WithDefaultToolsCapability(json, tools => tools.AddTool(new EchoTool()))
            .Build();
        await server.Start();
    });

await listener.Start();

// Client
using McpSdk.Adapter.ConsoleLogger;
using McpSdk.Adapter.System.Net.Http;
using McpSdk.Adapter.System.Text.Json;
using McpSdk.Client;

var json = new SystemJson();
var loggerFactory = new ClientConsoleLoggerFactory();
var http = new StreamableHttpClient("http://localhost:3000/mcp", loggerFactory);

var client = new ClientBuilder()
    .WithName("Demo Client")
    .WithVersion("1.0.0")
    .WithLogger(loggerFactory)
    .WithStreamableHttpTransport(json, http)
    .Build();

await client.Connect();

Capabilities

What the SDK serves as of the 2025-11-25 revision. ✅ supported · ❌ not implemented (deliberate scope choice).

Protocol & transport

Server — methods served

WithInstructions sets the server-level instructions on the initialize result — free-form guidance on using the server as a whole, which a client may feed to the model as a system prompt. It is omitted from the payload when unset. On the client side Connect returns the whole InitializeResult, so the negotiated version, capabilities, serverInfo, and instructions are all available after the handshake:

var init = await client.Connect();
Console.WriteLine(init.Instructions);

Server-emitted notifications: notifications/message, notifications/progress, notifications/cancelled, notifications/tools/list_changed, notifications/prompts/list_changed, notifications/resources/list_changed, notifications/resources/updated.

Client — server→client requests handled

The client surfaces inbound notifications/message as LogMessageReceived and notifications/progress as ProgressReceived.

Tools & content

License

Licensed under the MIT License.