minimal-mcp

The smallest MCP server that still covers the whole protocol: one file, one todo list, all three primitives, plus elicitation.

uv sync
uv run python smoke_test.py       # proves it works -- 12 checks
uv run mcp dev todo_server.py     # MCP Inspector -- poke at it in a browser

The one thing to remember

Each MCP primitive is defined by who decides to use it:

Primitive	Decided by	Here
Tools	the model	add_todo, complete_todo, remove_todo
Resources	the application	todos://all, todos://todo/{id}
Prompts	the user	plan_my_day

remove_todo also demonstrates elicitation — the tool pauses mid-call to ask the user "really delete this?" before acting. That's a capability a plain REST endpoint has no way to express.

Why one file

Everything lives in todo_server.py, top to bottom, in the order you'd want to read it: storage → wire types → server → tools → resources → prompts. No navigating between files to see the whole picture.

Storage is a plain in-memory dict — restarting clears it. That's deliberate: this project is about the protocol, not persistence.

Connecting it to a real host

claude mcp add todos -- uv --directory "<absolute path to this repo>" run python todo_server.py

Not yet verified against a real host — only against the Inspector and the smoke test.