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.

Run it locally

There are two ready-made environments. local is for dotnet run: sample data on, logs to the console. docker is for Docker Compose: sample data on, logs, traces and metrics to the Aspire dashboard, database on a volume, and the MCP Inspector next door. Both are for your machine. Neither is for production, which is why neither is the default.

Terminal window
dotnet run --project ./src/Presentation

launchSettings.json sets the environment to local and listens on https://localhost:7321, and on http://localhost:7320, which redirects to it. If your browser or curl doesn’t trust the .NET development certificate yet, run dotnet dev-certs https --trust once. The server is at /mcp.

Where What
/mcp The server. Streamable HTTP, stateless, JSON-RPC in and server-sent events out
/health/live Answers 200 while the process is up
/health/ready Answers 200 when the database can be reached
/.well-known/oauth-protected-resource/mcp Protected resource metadata, only when authentication is on
http://localhost:7325 The MCP Inspector, when running with Docker Compose
http://localhost:7326 Open WebUI, when running with Docker Compose and the demo profile
http://localhost:7322 The Aspire dashboard, with the logs, traces and metrics, when running with Docker Compose

The health endpoints answer without a token even when authentication is on, so a load balancer never needs to log in.

The MCP Inspector is the official test client, and Docker Compose runs it already pointed at http://api:7320/mcp. Open it, press Connect, and:

  • Tools lists every tool with its description, annotations and input schema, and gives you a form to call it. A result lists its movies, authors and reviews under Resource Links, and expanding one reads it.
  • Resources lets you read movies://top-rated, server://version or any movies://, authors:// or reviews:// URI, and the ids autocomplete as you type an id or a title.
  • Prompts renders each prompt with its arguments, and the title, name and id arguments autocomplete from the database.

Running with dotnet run instead? Start the Inspector yourself with npx @modelcontextprotocol/inspector and point it at https://localhost:7321/mcp. Node doesn’t read the system’s trusted certificates by default, so if it can’t connect, use Docker Compose instead.

Want to ask for things in plain English? The optional demo profile adds Open WebUI, already connected to the server.

Terminal window
docker compose --profile demo up -d --build

Open http://localhost:7326, dismiss the release notes and ask it to list the movies. It uses Kilo’s free gateway as the model, so there’s no account or key, but it only works online, and your prompts and tool results go to Kilo, a third party. Keep it to sample data. Solutions created with --include-auth leave it out, because Open WebUI has no token to send. Stop it with docker compose --profile demo down.

Docker Compose runs an OpenTelemetry Collector beside the server, and the collector forwards everything to the Aspire dashboard at http://localhost:7322. Open Traces to follow a request from the HTTP request through the tool call to the use case, Structured for the logs, each linked to its trace, and Metrics for request durations, EF Core queries and the runtime. The dashboard keeps everything in memory, so it’s empty again after a restart. The dashboard has no login, and the collector accepts OTLP from anyone on ports 7323 and 7324. That’s on purpose, so there’s nothing to sign in to on your machine, and it’s why the compose file is for your machine only. Don’t run it anywhere other people can reach.

The server only ever talks OTLP to the collector, and otel-collector.yaml decides where things go. To send them to a real backend, add its exporter there; the server doesn’t change. To see a dotnet run in the dashboard, start the collector and point the server at it:

Terminal window
docker compose up -d otel-collector
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:7323 dotnet run --project ./src/Presentation

The server is stateless, so a single tools/call works without an initialize first. These use the dotnet run address; with Docker Compose, use http://localhost:7320/mcp instead. The sample data uses a fixed seed, so these ids are the same on every machine. See the tool reference for every argument and result.

Terminal window
# One movie, with every review
curl -X POST "https://localhost:7321/mcp" \
-H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"movies_get","arguments":{"movieId":"cb188ef6-14e7-f85f-2f78-924c2ab26b28"}}}'
# Write a review
curl -X POST "https://localhost:7321/mcp" \
-H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"reviews_write","arguments":{"authorId":"01fa8b58-05d2-abd4-e55c-2633222dd0a5","movieId":"cb188ef6-14e7-f85f-2f78-924c2ab26b28","stars":5,"text":"Great film. I cried at the ending."}}}'
# Read a resource
curl -X POST "https://localhost:7321/mcp" \
-H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":3,"method":"resources/read","params":{"uri":"server://version"}}'
Terminal window
dotnet test

The tests build their own in-memory SQLite databases from the same migrations and seed, so nothing touches movie-reviews.db. Test your changes covers where a test goes, how the tests are written and how to check coverage before CI does.

The Dockerfile has a stage for each job, so you can build only what you need.

Stage What it does
build Restores and builds the solution
test Runs every test with coverage, and saves the result instead of failing the build
results Exports the test results, the coverage report and the exit code to your machine
publish Publishes the Presentation project
run The image you deploy
Terminal window
docker build . --target results --output type=local,dest=out

A failing test doesn’t fail the build, so the results still come out. Check out/exit-code: anything other than 0 means a test failed, and a pipeline built on these stages should fail on it.

Terminal window
docker build . --target run --tag worksonmymachine-movies:latest \
--build-arg VERSION_PREFIX=1.2.3 --build-arg VERSION_SUFFIX=beta

The server://version resource and the serverInfo in the initialize response then report 1.2.3-beta and the commit it was built from.