Dotnet MCP Builder

Building MCP servers in .NET

Write production-quality MCP servers and basic clients in C#/.NET using the official ModelContextProtocol 2.x packages, current transport behavior, modern primitives, and the 2026-07-28 spec rules.

When to invoke

• "Build an MCP server in C# or .NET."
• "Add a McpServerTool and register it."
• "Fix MapMcp, STDIO, or Streamable HTTP errors."
• "Use WithStdioServerTransport or HTTP transport."
• "Expose this prompt, resource, elicitation flow, MCP App, or Task in .NET."

Prerequisites and context

• Use official packages from the ModelContextProtocol NuGet profile, maintained by Microsoft and the MCP project.
• Target the stable 2.x line unless an existing project is pinned for a documented reason.
• Default new projects to .NET 10 when the user does not specify a target.
• Run dotnet build for non-trivial changes.
• Skip this skill for MCP work in other languages.

Mental model

A .NET MCP server is a normal Microsoft.Extensions.Hosting or WebApplication app that wires an MCP server through dependency injection.

builder.Services
    .AddMcpServer()
    .WithStdioServerTransport()      // OR .WithHttpTransport(...)
    .WithToolsFromAssembly()
    .WithPrompts<MyPrompts>()
    .WithResources<MyResources>();

Primitives are C# methods on attributed classes: [McpServerToolType] plus [McpServerTool], [McpServerPromptType] plus [McpServerPrompt], and [McpServerResourceType] plus [McpServerResource]. Parameters bind from JSON-RPC through System.Text.Json; descriptions become part of the JSON Schema the LLM sees.

Reference routing

Always load references/packages.md when creating a new project or when the package version is uncertain.

For multi-primitive tasks, load all matching references. For trivial edits in an existing file, apply the cardinal rules without loading every reference.

Cardinal rules

Transport decisions

For current-protocol HTTP mid-tool questions, prefer multi-round-trip InputRequiredException over legacy ElicitAsync.

Troubleshooting

Working style

• Make minimal, additive changes; add methods to existing primitive classes before restructuring.
• Confirm transport, .NET version, and primitives before scaffolding when context is unclear.
• For OAuth, reverse-proxy, and per-session HTTP wiring, read references/transport-http.md before coding.
• For MCP Apps or Tasks, read references/mcp-apps.md or package docs before using extension APIs.
• Point to the EverythingServer sample when a feature interaction remains unclear.

Progressive disclosure and bundled resources

• references/packages.md: current packages and version guidance.
• references/transport-stdio.md: STDIO server setup and stdout/stderr traps.
• references/transport-http.md: Streamable HTTP, OAuth, reverse proxy, stateful/stateless wiring.
• references/tool-primitive.md: tools, [McpServerToolType], [McpServerTool], descriptions, schemas.
• references/prompt-primitive.md: prompts and registration.
• references/resource-primitive.md: resources and registration.
• references/elicitation.md: InputRequiredException, URL mode, and legacy ElicitAsync.
• references/sampling.md: deprecated sampling guidance.
• references/roots.md: deprecated roots guidance.
• references/mcp-apps.md: interactive MCP Apps.
• references/server-features.md: completions, progress, filters, server instructions.
• references/client.md: basic .NET MCP client.
• references/testing.md: MCP Inspector, in-memory tests, mocks, and CI.

SDK vocabulary

Remember stateless-by-default HTTP behavior, discovery-first negotiation, input_required, down-level fallback, server-to-client (to-client) calls through IMcpServer, ILogger for normal logging, and highest-frequency breakage prevention. Legacy roots/sampling/logging, sampling/roots, sampling/roots/log, Sampling/elicitation/roots, and now-deprecated capabilities require transition notes. Load references for Add/modify tasks, Apps/Tasks, log/progress, and prompt/resource/elicitation/MCP work.

Output template

## .NET MCP result

**Status:** complete | needs changes | blocked
**Transport:** STDIO | Streamable HTTP | stateful HTTP | legacy SSE
**Packages:** `ModelContextProtocol` <version>, `ModelContextProtocol.AspNetCore` <version>
**Target framework:** `<TFM>`

| Primitive or feature | Registration | Reference used | Notes |
| --- | --- | --- | --- |
| Tool | `.WithToolsFromAssembly()` | `references/tool-primitive.md` | <description/schema note> |

### Validation
- `dotnet build`: pass | fail | not run (<reason>)
- STDIO stdout check: pass | fail | not applicable
- HTTP route check: pass | fail | not applicable
- Deprecated API check (`MCP9005`): pass | fail | not applicable

Quality gate

• Current stable 2.x packages are used or any non-2.x version is justified.
• Transport choice is explicit: STDIO, Streamable HTTP, stateful HTTP legacy, or legacy SSE.
• STDIO servers write no logs, banners, or tool output to stdout.
• HTTP routing uses app.MapMcp() or app.MapMcp("/mcp") intentionally.
• New tools, prompts, and resources include both attributes and registration lines.
• Tool and parameter [Description] attributes are present and useful.
• Deprecated roots, sampling, and MCP-channel logging are avoided for new work or documented with MCP9005 handling.
• dotnet build was run for non-trivial code changes or a concrete blocker is reported.

References

• ModelContextProtocol NuGet profile
• ModelContextProtocol API reference
• EverythingServer sample