Skip to content
Clean Model Context Protocol
Lean Mean Clean Apps

Five templates, one brand, one search box. Everything in the docs is in here, including the bits we hoped you'd skim.

Try one of these

Results say which template they came from, so you won't end up reading about Lambda when you wanted GraphQL. Again.

Secure the server

Out of the box the server runs wide open, and there’s no authentication code in it at all. Anyone who can reach /mcp can call every tool, including the one that deletes reviews. That’s lovely on a laptop and less lovely in production, so here’s how to close the door.

  1. Create the solution with --include-auth, and tell it who issues tokens and who they’re for:

    Terminal window
    dotnet new cleanmodelcontextprotocol --name WorksOnMyMachine.Movies \
    --include-auth --authority https://login.example.com --audience https://movies.example.com/mcp

    --authority is required with --include-auth, so dotnet new stops and says so if it’s missing. To point each environment at its own server, override the settings in appsettings.json or with environment variables:

    Terminal window
    Authentication__Authority=https://login.example.com
    Authentication__Audience=https://movies.example.com/mcp
  2. List the scopes a client should ask for, if your authorization server uses them.

    {
    "Authentication": {
    "Authority": "https://login.example.com",
    "Audience": "https://movies.example.com/mcp",
    "Scopes": ["movies.read", "movies.write"]
    }
    }
  3. Get a token from the authority for that audience, and send it.

    Terminal window
    curl -X POST "https://localhost:7321/mcp" -H "Authorization: Bearer eyJhbGciOi..." \
    -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
    -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

    Without a token, or with one from the wrong issuer or for the wrong audience, the server answers 401 Unauthorized with a WWW-Authenticate header that points at the metadata below.

Created the solution without --include-auth? The code isn’t hiding behind a setting, it isn’t there at all, so it goes in by hand. The quickest way to see every line is to let the template show you. Create a second solution with the same name and --include-auth next to yours, then compare the two:

Terminal window
dotnet new cleanmodelcontextprotocol --name WorksOnMyMachine.Movies --output ../with-auth \
--include-auth --authority https://login.example.com --audience https://movies.example.com/mcp
git diff --no-index src ../with-auth/src
git diff --no-index tests ../with-auth/tests

Copy across what’s new: the Microsoft.AspNetCore.Authentication.JwtBearer package reference, the Authentication folder and its section in appsettings.json, the authentication regions in startup, RequireAuthorization() on /mcp, the MCP challenge and protected resource metadata, and the authentication tests, so coverage stays where it was. The optional-token-auth skill in .agents/skills walks your coding agent through the same steps.

With authentication on, the server publishes protected resource metadata at /.well-known/oauth-protected-resource/mcp:

{
"resource": "https://movies.example.com/mcp",
"authorization_servers": ["https://login.example.com"],
"scopes_supported": ["movies.read", "movies.write"],
"resource_name": "Clean Model Context Protocol"
}

A client that gets a 401 reads it, discovers the authorization server, and runs the OAuth flow itself. Claude, VS Code and the Inspector all do this, so for the user it’s a sign-in screen and then everything works. Your server never sees a password and never stores a secret. Tokens are validated against the authority’s published keys.

/health/live and /health/ready answer without a token, so load balancers and curious humans can still check the lights are on. Everything under /mcp needs one: tools, resources, prompts and completions alike.

AuthenticationSettings reads the Authentication section. The server registers the JWT bearer handler for authentication and the MCP handler for the challenge and the metadata, and puts RequireAuthorization() on the /mcp endpoint. An empty authority still lets every request through, which is how the tests run, so make sure every environment you deploy to sets one. The tools don’t know either way, which is why adding authentication doesn’t touch a single one.