Skip to main content
skill CX Codex

mcp · managedcode — Claude Code skill: what it does, how to install

mcp guides building and consuming Model Context Protocol servers and clients in C# on .NET 8+, covering stdio, Streamable HTTP, and tools.

MIT ★ 521 updated 2026-10-29

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add managedcode/dotnet-skills --skill mcp -a claude-code
Open on GitHub

What mcp does

This skill provides architecture guidance and code patterns for the official MCP C# SDK v2.2. It helps pick the right package (ModelContextProtocol, ModelContextProtocol.Core, or ModelContextProtocol.AspNetCore) depending on whether you run a local child process or a remote web service.

The guidance covers stdio and Streamable HTTP transports, registering tools via attributes, handling resources and prompts, and negotiating MCP 2026-07-28 capabilities. It also covers wiring discovered tools into IChatClient and configuring session lifecycles in ASP.NET Core.

Projects must target .NET 8 or newer because the official C# SDK does not support earlier runtimes.

What it helps with

  • configure stdio or Streamable HTTP transports for .NET MCP endpoints
  • expose tools, resources, and prompts using the official C# SDK
  • connect a .NET client to an external MCP host and pass tools to IChatClient
  • manage session lifecycles and authorization in ASP.NET Core

Example prompts for the agent

  • Set up a local C# MCP server using stdio transport and register a tool
  • Configure ASP.NET Core to host a remote MCP server with Streamable HTTP
  • Connect a .NET app to an existing MCP server and feed discovered tools to IChatClient

How to install mcp

1Skills CLI (Vercel)

npx skills add managedcode/dotnet-skills --skill mcp -a claude-code

2Manually: put the files in place

~/.claude/skills/mcp/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/mcp/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about mcp

How to install mcp in Claude Code?

Run npx skills add managedcode/dotnet-skills --skill mcp -a claude-code in your terminal.

What does the mcp skill do?

It guides coding assistants when writing C# MCP servers or clients, enforcing correct SDK patterns, transports, and protocol schemas.

Which .NET packages and versions are needed?

It targets .NET 8+ and the v2.2 SDK using ModelContextProtocol, ModelContextProtocol.Core, or ModelContextProtocol.AspNetCore.

Source text

SKILL.md · MIT
---
name: mcp
description: "Build or consume Model Context Protocol (MCP) servers and clients in .NET using the official MCP C# SDK, including stdio, Streamable HTTP, tools, prompts, resources, and capability negotiation. USE FOR: .NET MCP servers or clients; stdio versus HTTP transport choices; tools, resources, prompts, completions, and capability negotiation. DO NOT USE FOR: unrelated stacks; generic tasks that do not need this specific guidance. INVOKES: inspect the repository context, edit targeted files, and run relevant build, test, lint, or validation commands when changes are made."
compatibility: "Requires the official MCP C# SDK packages (`ModelContextProtocol.Core`, `ModelContextProtocol`, or `ModelContextProtocol.AspNetCore`) on .NET 8+; current guidance targets the v2.2 SDK and MCP 2026-07-28."
---

# MCP C# SDK for .NET

## Trigger On

- building or consuming MCP servers from a .NET application or library
- choosing between stdio and HTTP transport for MCP
- exposing tools, resources, prompts, completions, or logging to an MCP host
- connecting a .NET app to an existing MCP server and passing discovered tools into `IChatClient`
- bootstrapping a minimal MCP client/server from the `.NET AI` quickstarts or publishing a server to the MCP Registry
- implementing capability-aware flows such as roots, sampling, elicitation, subscriptions, session resumption, or enterprise managed authorization

## Use This Skill Instead Of

- Use `mcp` when **protocol interoperability** is the requirement.
- Use `microsoft-extensions-ai` when you only need model/provider abstraction or local tool orchestration without the MCP wire protocol.
- Use `microsoft-agent-framework` when the main problem is agent orchestration; combine it with `mcp` only when those agents must consume or expose MCP endpoints.
- Use the `.NET AI` quickstarts for the very first vertical slice, then come back here to harden transport, capability negotiation, publishing, and host interoperability.

## Documentation

- [MCP C# SDK overview](https://csharp.sdk.modelcontextprotocol.io/)
- [Getting Started](https://csharp.sdk.modelcontextprotocol.io/concepts/getting-started.html)
- [API reference](https://csharp.sdk.modelcontextprotocol.io/api/ModelContextProtocol.html)
- [Conceptual docs](https://csharp.sdk.modelcontextprotocol.io/concepts/index.html)
- [Versioning policy](https://csharp.sdk.modelcontextprotocol.io/versioning.html)
- [Experimental APIs](https://csharp.sdk.modelcontextprotocol.io/experimental.html)
- [MCP C# SDK repository](https://github.com/modelcontextprotocol/csharp-sdk)
- [Model Context Protocol specification](https://modelcontextprotocol.io/specification/)

## References

Load only what the task needs:

- [references/patterns.md](references/patterns.md) - current server/client patterns, transports, capabilities, filters, and chat-client integration
- [references/security.md](references/security.md) - safe error handling, auth boundaries, stdio logging hygiene, and defensive tool/resource patterns

## Package Selection

| Package | Choose when |
|---------|-------------|
| `ModelContextProtocol.Core` | You only need a client or low-level server APIs and want the smallest dependency set. |
| `ModelContextProtocol` | You want the main SDK package with hosting, DI, attribute discovery, and stdio server support. Start here for most projects. |
| `ModelContextProtocol.AspNetCore` | You are hosting a remote MCP server in ASP.NET Core over HTTP. This includes the main package. |

## Transport Selection

| Transport | Use when | Notes |
|-----------|----------|-------|
| `StdioClientTransport` / `WithStdioServerTransport()` | The MCP server should run as a local child process. | Best for local tooling and editor/agent integrations. |
| `HttpClientTransport` + `HttpTransportMode.StreamableHttp` | The server is remote or should be reachable over HTTP. | Recommended HTTP transport; supports streaming and session resumption. |
| `HttpTransportMode.Sse` | You must connect to an older SSE-only server. | Legacy compatibility only; do not choose this for new servers. |

## Current v2.2 Notes

- The August 2026 `.NET AI` MCP documentation separates a getting-started hub, client and server quickstarts, MCP Registry publishing, and a server-resource index. Use those pages to bootstrap a vertical slice, then return to the C# SDK docs here for exact transport, capability, authorization, and lifecycle behavior.
- SDK `v2.0.0` aligns with MCP `2026-07-28`: HTTP is stateless by default, clients negotiate with `server/discover` before falling back to legacy `initialize`, Tasks move to `ModelContextProtocol.Extensions.Tasks`, and Roots, Sampling, and Logging are deprecated for the new protocol. Set `HttpServerTransportOptions.Stateless = false` only for an intentional stateful compatibility requirement.
- SDK `v2.1.0` adds an opt-in `subscriptions/listen` server handler, keeps AutoDetect usable after a provisional SSE failure, preserves HTTP status codes across target frameworks, and falls back to `initialize` when `server/discover` fails at the HTTP layer. Add custom notification streams only when both peers negotiate the extension.
- SDK `v2.2.0` adds `HttpServerSessionMode` so one ASP.NET Core endpoint can serve stateful and stateless clients across the MCP `2025-11-25` and `2026-07-28` protocol versions. Choose the mode explicitly, test both negotiated paths when compatibility matters, and upgrade before working around malformed percent-encoded request headers because the release fixes that decoding failure.
- Before moving from `v1.4.x`, update structured-result consumers to accept non-object values directly, require `Tool.inputSchema` in custom payloads, move Tasks to the extension package, and test PKCE S256 plus issuer validation in OAuth metadata.
- Enterprise managed authorization now has an SDK surface through `IdentityAssertionGrantProvider` for the Identity Assertion Authorization Grant flow. Use it only when the enterprise SSO and MCP authorization-server contract is part of the actual scenario.
- `StdioClientTransportOptions.InheritEnvironmentVariables` controls whether child-process MCP servers inherit the parent environment. Set it intentionally when launching untrusted or third-party servers.
- Streamable HTTP session `DELETE` is hardened to require the same authenticated user that opened the session. Do not build custom session cleanup paths that bypass that authorization check.
- Stdio transport no longer logs child-process environment variables at trace level, but server authors should still treat environment variables as secrets.

```mermaid
flowchart LR
    A["Need MCP interoperability in .NET"] --> B{"Role?"}
    B -->|"Expose MCP surface"| C{"Where will it run?"}
    B -->|"Consume an MCP server"| D{"Transport?"}
    C -->|"Local child process"| E["ModelContextProtocol\nAddMcpServer()\nWithStdioServerTransport()"]
    C -->|"Remote HTTP endpoint"| F["ModelContextProtocol.AspNetCore\nAddMcpServer()\nWithHttpTransport()\nMapMcp()"]
    D -->|"stdio"| G["StdioClientTransport\nMcpClient.CreateAsync()"]
    D -->|"HTTP"| H["HttpClientTransport\nAutoDetect or StreamableHttp"]
    E --> I["Register tools/resources/prompts"]
    F --> I
    G --> J["Check ServerCapabilities\nbefore optional features"]
    H --> J
```

## Workflow

1. Pick the package and transport first.
   - Local child-process server: `ModelContextProtocol` + `WithStdioServerTransport()`.
   - Remote server: `ModelContextProtocol.AspNetCore` + `WithHttpTransport()` + `MapMcp()`.
   - Client-only app: start with `ModelContextProtocol` or `ModelContextProtocol.Core`.
   - Registry distribution: pair a minimal server with the MCP Registry publishing flow only after the server contract is stable.

2. Model the MCP surface explicitly.
   - Tools: `[McpServerToolType]` + `[McpServerTool]`
   - Resources: `[McpServerResourceType]` + `[McpServerResource]`
   - Prompts: `[McpServerPromptType]` + `[McpServerPrompt]`
   - Use custom handlers or filters only for cross-cutting behavior, protocol extensions, or advanced routing.

3. Prefer attribute discovery for straightforward servers.

```csharp
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using ModelContextProtocol.Server;
using System.ComponentModel;

var builder = Host.CreateApplicationBuilder(args);
builder.Logging.AddConsole(options =>
{
    options.LogToStandardErrorThreshold = LogLevel.Trace;
});

builder.Services
    .AddMcpServer()
    .WithStdioServerTransport()
    .WithToolsFromAssembly();

await builder.Build().RunAsync();

[McpServerToolType]
public static class EchoTool
{
    [McpServerTool, Description("Echoes the message back to the client.")]
    public static string Echo(string message) => $"hello {message}";
}
```

4. For HTTP servers, use the ASP.NET Core transport and map the endpoint directly.

```csharp
using ModelContextProtocol.Server;
using System.ComponentModel;

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddMcpServer()
    .WithHttpTransport()
    .WithToolsFromAssembly();

var app = builder.Build();
app.MapMcp("/mcp");
app.Run();

[McpServerToolType]
public static class EchoTool
{
    [McpServerTool, Description("Echoes the message back to the client.")]
    public static string Echo(string message) => $"hello {message}";
}
```

5. When consuming a server, use `McpClient.CreateAsync(...)` and stay capability-aware.

```csharp
using ModelContextProtocol.Client;
using ModelContextProtocol.Protocol;

var transport = new StdioClientTransport(new StdioClientTransportOptions
{
    Name = "Everything",
    Command = "npx",
    Arguments = ["-y", "@modelcontextprotocol/server-everything"],
});

await using var client = await McpClient.CreateAsync(transport);

IList<McpClientTool> tools = await client.ListToolsAsync();

if (client.ServerCapabilities.Prompts is not null)
{
    var prompts = await client.ListPromptsAsync();
}
```

6. Treat optional features as negotiated capabilities, not assumptions.
   - Client capabilities: configure `McpClientOptions.Capabilities` for roots, sampling, and elicitation.
   - Server capabilities are inferred from registered features.
   - Check `client.ServerCapabilities` before using completions, logging, prompt list-change notifications, or resource subscriptions.
   - Use `client.NegotiatedProtocolVersion` or `server.NegotiatedProtocolVersion` only when version-specific behavior matters.

7. Keep HTTP guidance current.
   - Streamable HTTP is the recommended transport for remote servers.
   - `MapMcp()` also serves SSE compatibility endpoints for older clients.
   - HTTP clients can use `AutoDetect` by default, or force `StreamableHttp` / `Sse`.
   - Session resumption is available for Streamable HTTP through `McpClient.ResumeSessionAsync(...)`.
   - For authenticated Streamable HTTP sessions, cleanup and resume operations must preserve the same user boundary.

8. Treat the `.NET AI` MCP quickstarts as bootstrap examples.
   - `build-mcp-client` and `build-mcp-server` are good starting points when the surrounding app is still MEAI-centric.
   - `publish-mcp-registry` is the distribution step, not the design step. Stabilize the protocol surface before publishing.

9. Respect current error and serialization rules.
   - Tool exceptions normally come back as `CallToolResult.IsError == true`.
   - Throw `McpProtocolException` only for protocol-level JSON-RPC failures.
   - `McpClientTool` inherits from `AIFunction`, so discovered tools can be passed directly into `IChatClient`.
   - Experimental APIs use `MCPEXP...` diagnostics; suppress them intentionally, not globally by accident.
   - If you use a custom `JsonSerializerContext`, prepend `McpJsonUtilities.DefaultOptions.TypeInfoResolver` so MCP protocol types keep the SDK's contract.

## Anti-Patterns To Avoid

| Anti-pattern | Why it causes trouble | Better approach |
|--------------|-----------------------|-----------------|
| Picking HTTP transport for a purely local child-process scenario | Adds unnecessary hosting, auth, and deployment surface | Use stdio for local/editor-hosted integrations |
| Treating SSE as the default remote transport | Locks new work to legacy behavior | Prefer Streamable HTTP and keep SSE only for backward compatibility |
| Writing tools without `[Description]` metadata | Hosts and models lose schema clarity | Describe tool purpose and parameters explicitly |
| Returning huge binary/text payloads from every tool call | Bloats context and slows hosts | Return focused content and move large data to resources |
| Logging to stdout on stdio servers | Corrupts the protocol stream | Send logs to stderr |
| Assuming prompts/resources/logging/completions exist | Breaks against partial implementations | Check negotiated capabilities first |
| Using filters for normal business logic | Makes handlers opaque and hard to reason about | Keep filters for cross-cutting policy, audit, or protocol plumbing |

## Deliver

- a correctly packaged MCP server or client that matches the deployment topology
- explicit tool/resource/prompt definitions with descriptions and bounded payloads
- capability-aware handling for optional MCP features
- validation notes for transport, auth boundary, and host/client interoperability

## Validate

- chosen package matches the topology: `Core`, `ModelContextProtocol`, or `AspNetCore`
- stdio servers do not write logs or diagnostics to stdout
- HTTP servers use `MapMcp()` and are tested at the final route, for example `/mcp`
- tools, resources, and prompts use current `[McpServer*]` attributes or documented handler/filter alternatives
- client code checks `ServerCapabilities` before using subscriptions, completions, logging, or prompt/resource list-change flows
- Streamable HTTP is the default for new remote servers; SSE is used only for legacy compatibility
- experimental APIs and custom serialization settings are reviewed intentionally rather than copied blindly

© managedcode · MIT · managedcode/dotnet-skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

mcp by other authors comes first.

mcp vercel-labs This skill helps build MCP servers that render interactive json-render UIs in Claude, ChatGPT, Cursor, and VS Code. CX Codex +1 5,900installs csharp-mcp-server official github The csharp-mcp-server rule guides C# MCP server work with the Model Context Protocol SDK. It fits projects where tools, prompts, DI, and stdio transport need a consistent setup. CX Codex +1 ★ 41,430repo stars configure-auth dotnet configure-auth adds authentication and authorization to a Blazor Web App based on its render mode. It prevents runtime crashes with Identity and interactive routing. CX Codex +1 4,200installs api-versioning codewithmukesh Guides your agent through ASP.NET Core API versioning using the Asp.Versioning library. Useful when adding URL segment versions or deprecating legacy contracts. CX Codex +1 4,000installs create-datadriven-aspnetcore dotnet create-datadriven-aspnetcore generates ASP.NET Core CRUD code — Razor Pages, Blazor components, controllers, and Minimal APIs — aligned with project styles and EF Core without CLI generators. CX Codex +1 3,900installs dotnet-security-owasp wshaddix dotnet-security-owasp flags OWASP Top 10 vulnerabilities in .NET solutions and guides safe coding. Useful for reviewing ASP.NET Core endpoints and data queries. CX Codex +1 175installs ASP.NET Core Debugger — MCP Server for AI Agents magna-nz ASP.NET Core Debugger — MCP Server for AI Agents is an MCP server for interactive .NET and ASP.NET Core debugging through netcoredbg and DAP. It pauses code, reads runtime values, and tests fixes live. CX Codex +1 ★ 16repo stars

From the same set38

The whole set →
signalr Guides the implementation and review of SignalR hubs, streaming, groups, and reconnection logic in ASP.NET Core. CX Codex +1 ★ 521repo stars code-testing-implementer The code-testing-implementer subagent implements one test-plan phase, writes the test files, and checks whether they build and pass. Use it to carry out a phase or run a build-test-fix cycle. CX Codex ★ 521repo stars microsoft-extensions-ai Skill for building provider-agnostic .NET AI integrations with Microsoft.Extensions.AI: chat clients, embeddings, tools, structured output, and evaluation. CX Codex +1 ★ 521repo stars unit-test-generation The unit-test-generation prompt guides an agent through writing focused unit tests that check behavior and catch plausible bugs. Use it when adding tests to existing code or starting a new test suite. CX Codex +1 ★ 521repo stars wpf Rules and patterns for WPF apps: bindings, commands, threading, styles. Fits UI work, MVVM refactoring, or moving a project from .NET Framework to .NET. CX Codex +1 ★ 521repo stars worker-services worker-services guides the agent in building long-running .NET background services with BackgroundService, PeriodicTimer, and proper dependency scoping. CX Codex +1 ★ 521repo stars aspire This skill guides work on Aspire AppHosts for distributed C# and TypeScript applications. Use it to wire services, configure integrations, or test an Aspire topology. CX Codex +1 ★ 521repo stars improve-skill-quality improve-skill-quality — a skill for the dotnet/skills repository that traces regressions, timeouts, activation failures, and inconclusive evaluation results back to their source. CX Codex +1 ★ 521repo stars

Project sponsors

Companies that keep this analytics open