Code4mk.McpServer.Template 1.0.0

.NET MCP Server Template

A production-ready Model Context Protocol server for ASP.NET Core in one command. Sign-in with any identity provider, interactive UIs inside the chat, typed API clients, tests, Docker and docs: the parts that take weeks are already done, so you write tools.

dotnet new install Code4mk.McpServer.Template
dotnet new code4mk-mcp -n Acme.Mcp -o acme-mcp

Built on the official MCP C# SDK 2.0 and .NET 10.

Why this template

Remote MCP servers need real OAuth, and that's the hard part. MCP clients such as Claude expect OAuth 2.1 with dynamic client registration, PKCE, and protected resource metadata. Most identity providers (Entra ID, Google, Okta, ...) don't offer dynamic registration. This template ships an OIDC proxy that makes any OIDC provider work with three settings, including the consent screen, encrypted token storage and Redis for multiple instances. Users sign in once: expired tokens renew silently with rotating refresh tokens, and sign-ins survive restarts and deploys.

Tools can show real UI, not just text. MCP Apps are wired end to end: React + Tailwind views that follow the host's theme, call your tools themselves (paging, drill-down), validate every response, and preview with sample data without a server.

The structure stays clean as it grows. Tools → services → integrations, one direction, enforced by architecture tests: the build fails if a tool skips auth, calls an API directly, or leaks external models.

Errors the model can fix. Every tool and prompt argument is validated before your code runs; the model gets a list like request.durationDays: High-priority projects must be 90 days or less. and retries correctly.

An MCP App: the tool's result as a dashboard; selecting an owner calls another tool from the view	Consent before a new MCP client connects, then sign-in at your identity provider

Quick start

dotnet new install Code4mk.McpServer.Template
dotnet new code4mk-mcp -n Acme.Mcp -o acme-mcp
cd acme-mcp
cp .env.example .env                   # set MCP_AUTH_MODE=none for a first run without an identity provider
dotnet watch --project src/Acme.Mcp    # → Server running at http://localhost:5080
npx @modelcontextprotocol/inspector    # Streamable HTTP → http://localhost:5080/mcp

-n is the .NET name (PascalCase), -o the folder. Namespaces, the solution, Docker names and GUIDs follow it.

Connect a real identity provider: register one web app with redirect URI http://localhost:5080/oauth/callback, then set OIDC_DISCOVERY_URL, OIDC_CLIENT_ID and OIDC_CLIENT_SECRET in .env and MCP_AUTH_MODE=required. Add the server in Claude (Settings → Connectors → Add custom connector) and it opens your login page.

What you get

Project layout

acme-mcp/
├── src/Acme.Mcp/
│   ├── Capabilities/       Tools/, Resources/, Prompts/: what the server exposes (thin)
│   ├── Services/           Business logic
│   ├── Models/             Request / response DTOs
│   ├── Integrations/       One folder per external API
│   ├── Core/               Auth, MCP setup and filters, validation, settings, errors: plumbing you rarely touch
│   └── ui_dist/            Built MCP App bundles
├── ui/                     MCP App views (React + Vite + Tailwind)
├── tests/                  Unit, Integration, Architecture (mirror src/)
├── docs/                   Guides and ADRs
└── docker/                 Dockerfile, Compose

Adding a tool is one class; there is no registration line:

[McpServerToolType]
[Authorize]
public sealed class InvoiceTools(IInvoiceService invoices)
{
    [McpServerTool(Name = "get_invoice", ReadOnly = true, UseStructuredContent = true)]
    [Description("Gets an invoice by number.")]
    public Task<InvoiceDto> GetInvoice(
        [Required, RegularExpression("^INV-[0-9]{6}$")] string number,
        AppUser user,
        CancellationToken cancellationToken) =>
        invoices.GetAsync(number, user, cancellationToken);
}

Works with

• Clients: Claude (claude.ai and Desktop), VS Code, Cursor, MCP Inspector, and any client that speaks Streamable HTTP with OAuth.
• Identity providers: anything with an OpenID Connect discovery URL.
• Hosting: anywhere a container runs; set APP_URL behind a reverse proxy.

Documentation

Each generated project includes its docs. Browse them on GitHub:

• Development guides: getting started, configuration, tools, validation, MCP Apps, API clients, auth, testing, connecting clients
• MCP Apps UI workspace
• Architecture decisions
• Changelog

Requirements: .NET 10 SDK. Optional: Docker; Node 22+ and pnpm for MCP App views.

Contributing

Issues and pull requests are welcome. To work on the template itself:

git clone https://github.com/code4mk/dotnet-mcp-server-template
dotnet new install ./dotnet-mcp-server-template/templates/DotnetMcpTemplate --force
dotnet new code4mk-mcp -n Sample.Mcp -o ../sample-mcp     # always create projects outside the repo

• DotnetMcpTemplate (and dotnetmcptemplate-slug) are placeholders; keep them. Package versions live in templates/DotnetMcpTemplate/Directory.Packages.props.
• CI creates a project from the template, builds and tests it, checks the UI bundles, and packs the template.
• Changing, testing and publishing the template: nuget-publish.md.

License

MIT © Code4mk