McpSdk.Adapter.System.Text.Json 1.1.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

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.