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.
Run it
Section titled “Run it”dotnet run --project ./src/PresentationlaunchSettings.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.
docker compose up -d --buildCompose builds the run stage, starts the MCP Inspector, an OpenTelemetry Collector and the Aspire dashboard next to it, and publishes the server on http://localhost:7320/mcp. Shut it down with docker compose down, or docker compose down -v to drop the database too.
docker build . --target run --tag worksonmymachine-movies:localdocker run --rm -p 7320:7320 -e DOTNET_ENVIRONMENT=docker worksonmymachine-movies:localWithout Compose there’s no collector, so the logs stay on the console and nothing else is exported. Set OTEL_EXPORTER_OTLP_ENDPOINT to send them to a collector of your own.
Find your way around
Section titled “Find your way around”| 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.
Use the Inspector
Section titled “Use the Inspector”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://versionor anymovies://,authors://orreviews://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.
Chat with it
Section titled “Chat with it”Want to ask for things in plain English? The optional demo profile adds Open WebUI, already connected to the server.
docker compose --profile demo up -d --buildOpen 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.
See the telemetry
Section titled “See the telemetry”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:
docker compose up -d otel-collectorOTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:7323 dotnet run --project ./src/PresentationTry the tools from the terminal
Section titled “Try the tools from the terminal”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.
# One movie, with every reviewcurl -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 reviewcurl -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 resourcecurl -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"}}'Run the tests
Section titled “Run the tests”dotnet testThe 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.
Run just one part of the Dockerfile
Section titled “Run just one part of the Dockerfile”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 |
docker build . --target results --output type=local,dest=outA 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.
Stamp a version
Section titled “Stamp a version”docker build . --target run --tag worksonmymachine-movies:latest \ --build-arg VERSION_PREFIX=1.2.3 --build-arg VERSION_SUFFIX=betaThe server://version resource and the serverInfo in the initialize response then report 1.2.3-beta and the commit it was built from.