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.

Troubleshooting

Most first-run problems aren’t in the server. They’re in the plumbing around it: a port that’s already taken, an Inspector looking for the server on the wrong host, or Docker that hasn’t woken up.

The MCP Inspector at http://localhost:7325 won’t connect

Section titled “The MCP Inspector at http://localhost:7325 won’t connect”

Symptom: Opening http://localhost:7325 and clicking Connect fails to reach the MCP server.

When started with docker compose up -d --build, the MCP Inspector runs inside the Compose network (cleanmodelcontextprotocol_network), not on your host machine. Inside that network the MCP server’s hostname is api, not localhost. To a container, localhost is itself, which is a lonely place to look for a server.

  • In the Docker-hosted Inspector at http://localhost:7325, keep Transport Type set to Streamable HTTP and URL set to http://api:7320/mcp. If you change the URL to http://localhost:7320/mcp, the Inspector container tries to connect to itself and fails.
  • If you run a separate Inspector directly on your host machine (for example npx @modelcontextprotocol/inspector), point it at http://localhost:7320/mcp for Docker or https://localhost:7321/mcp for dotnet run.

The chat demo on port 7326 isn’t running

Section titled “The chat demo on port 7326 isn’t running”

Symptom: http://localhost:7326 refuses to connect after docker compose up -d --build, or the chat service isn’t in docker-compose.yml.

  • The Open WebUI chat container sits behind the demo Compose profile so a normal docker compose up doesn’t pull a multi-gigabyte image. Start it with:
    Terminal window
    docker compose --profile demo up -d --build
  • Open http://localhost:7326. It needs no login (WEBUI_AUTH is off) and no API key. It uses Kilo’s free gateway (kilo-auto/free) with the MCP server already connected.
  • If you generated the solution with --include-auth, the chat service is left out of docker-compose.yml because Open WebUI has no way to acquire and send an OAuth bearer token to the MCP server.

Symptom: dotnet run stops with Failed to bind to address https://127.0.0.1:7321: address already in use, or docker compose up fails with Bind for 0.0.0.0:7320 failed: port is already allocated.

Each Lean Mean Clean template has its own block of ten ports so different templates don’t step on each other. Clean Model Context Protocol uses 7320 to 7329 (7320 HTTP, 7321 HTTPS, 7322 Aspire dashboard, 7323 and 7324 OpenTelemetry Collector, 7325 MCP Inspector, 7326 Open WebUI chat demo). A clash usually means an earlier copy of this template is still running somewhere, quietly hogging the port.

  • Check what’s running in Docker and stop it:
    Terminal window
    docker compose --profile demo ps
    docker compose --profile demo down
  • Find a stray host process holding the port (lsof -i :7320 on macOS and Linux, netstat -ano | findstr :7320 on Windows) and stop it.
  • To move a Docker port, change the left-hand side of its mapping in docker-compose.yml and check the mapped port with:
    Terminal window
    docker compose port api 7320
  • To move the dotnet run ports, edit applicationUrl in src/Presentation/Properties/launchSettings.json.

Browser certificate warning or empty curl reply on dotnet run

Section titled “Browser certificate warning or empty curl reply on dotnet run”

Symptom: curl or an MCP client fails against https://localhost:7321/mcp with a TLS certificate error, or calling http://localhost:7320/mcp under dotnet run returns 307 Temporary Redirect.

In the local environment (dotnet run --project ./src/Presentation), Kestrel listens on both http://localhost:7320 and https://localhost:7321 and redirects HTTP to HTTPS. The development certificate is new to your machine, so your browser treats it like a stranger until you introduce them.

  • Trust the .NET development certificate once on your machine:
    Terminal window
    dotnet dev-certs https --trust
  • Point local MCP clients and curl at https://localhost:7321/mcp when using dotnet run.
  • Under docker compose up -d --build, the container runs in the docker environment and serves plain HTTP at http://localhost:7320/mcp with no redirect.

.NET SDK version refused by dotnet new or global.json

Section titled “.NET SDK version refused by dotnet new or global.json”

Symptom: dotnet new cleanmodelcontextprotocol refuses to run because the SDK constraint [10.0.100,) isn’t met, or dotnet build fails with NETSDK1141 / A compatible .NET SDK was not found.

Previews are fun, but the template only promises to work on a stable SDK. Both .template.config/template.json and the generated global.json require a stable .NET 10 SDK (10.0.100 or newer, rolling forward to the latest feature band with allowPrerelease: false).

  • Check which SDKs are installed:
    Terminal window
    dotnet --list-sdks
  • Install the current stable .NET 10 SDK. If you only have a preview SDK installed on the machine, either install the stable SDK alongside it or set "allowPrerelease": true in global.json.

Symptom: Running dotnet new cleanmodelcontextprotocol --include-auth stops before writing any files and exits with code 102 (Invalid option(s) / missing mandatory option --authority).

When --include-auth is switched on, --authority is required. Stopping at the door beats shipping a solution with a blank OAuth issuer. Pass the authority (and optionally --audience) alongside --include-auth:

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

See Secure the server for configuring OAuth 2.1 tokens after generation.

Symptom: docker compose up -d --build fails with Cannot connect to the Docker daemon or error during connect.

Docker doesn’t start itself, however much we’d like it to. Start Docker Desktop (or the Docker service on Linux) and wait for docker info to return cleanly before running docker compose up -d --build. You don’t need Docker for dotnet build, dotnet test or dotnet run --project ./src/Presentation; the integration tests run against an in-memory SQLite database.

Symptom: Startup migration or a write tool fails with Microsoft.Data.Sqlite.SqliteException (0x80004005): SQLite Error 5: 'database is locked'.

dotnet run writes to src/Presentation/movie-reviews.db. SQLite lets plenty of readers share a file but only one writer at a time. A lock means another process is holding an open write transaction against that file, usually a second dotnet run terminal or a database viewer.

  • Stop the other process holding src/Presentation/movie-reviews.db.
  • If you want to wipe the local database and re-seed the sample data from scratch, stop the server, delete src/Presentation/movie-reviews.db (and any -shm or -wal files beside it), and start the server again.
  • In Docker Compose, docker compose down -v removes the movie-reviews-data volume so the next docker compose up -d starts with a fresh database.