todos-server — the reference MCP server

A small project todo board where every server-side MCP feature has a real job: tools that mutate state, resources that expose it, prompts that seed conversations, sampling that borrows the connected host's model, elicitation that asks the user, progress and logs while it works, and per-resource subscriptions that announce every change. It is the workload cli-client (the reference host) connects to out of the box — think of it as the "polls app" of MCP servers: small enough to read in one sitting, real enough that nothing in it is contrived.

It serves both protocol revisions at once — 2026-07-28 and 2025-11-25 are negotiated per connection, from the same code — and both transports: stdio and Streamable HTTP.

Run it

From the repo root (first time: pnpm install && pnpm build:all):

# stdio — for hosts that spawn their servers as child processes
pnpm --filter @mcp-examples/todos-server start

# Streamable HTTP — for remote-style connections (default port 3000; --port to change)
pnpm --filter @mcp-examples/todos-server start:http

Over stdio the server speaks on stdin/stdout (its own diagnostics go to stderr). Over HTTP it serves http://127.0.0.1:3000/mcp via createMcpHandler's per-request model.

There is no era flag on the server: serveStdio and createMcpHandler detect each connection's revision during the handshake and pin the instance accordingly, so a 2025-era client and a 2026-era client can talk to the same process — simultaneously, over HTTP.

Connect cli-client to it

# Two terminals: serve over HTTP, then point the reference host at it
pnpm --filter @mcp-examples/todos-server start:http                          # terminal A
pnpm --filter @mcp-examples/cli-client start -- --server http://127.0.0.1:3000/mcp   # terminal B

# Same, but force the 2025-era handshake on the client to see the legacy arm in action
pnpm --filter @mcp-examples/cli-client start -- --server http://127.0.0.1:3000/mcp --legacy

The client's status line shows what was negotiated: connected to "todos" (2026-07-28, 8 tools, …) vs (2025-11-25, …).

You don't need the HTTP step for a quick look — running cli-client with no arguments spawns this server over stdio automatically.

Any other mcpServers-style host can spawn it too:

{
    "mcpServers": {
        "todos": { "command": "npx", "args": ["-y", "tsx", "/absolute/path/to/examples/todos-server/server.ts"] }
    }
}

What demonstrates what

The two protocol eras differ in how interactive conversations travel: on 2025-era connections the wire carries pushed elicitation/create / sampling/createMessage requests; on 2026-07-28 the server returns input_required results and the client retries the call with the answers. The interactive tools (brainstorm_tasks, clear_done, prioritize) are written once in the input_required style — on 2025-era connections the SDK's default-on legacy shim performs the push-style round trips for them, so there is no era branch in any handler. (For a side-by-side of the two wire styles written by hand, see examples/elicitation.)

One serving-mode caveat: over HTTP with a 2025-era client, createMcpHandler's default stateless posture has no return path for push-style server→client requests, so the sampling/elicitation tools refuse cleanly on that leg (stdio is unaffected; 2026-07-28 HTTP is unaffected).

Configuration

Layout

server.ts   transport entry: serveStdio by default, createMcpHandler + node adapter behind --http
todos.ts    the application: state, tools, resources, prompts, subscriptions — every feature above

This package is intentionally server-only; its end-to-end coverage comes from the cli-client scripted e2e, which drives it across stdio + HTTP on both protocol eras in CI.

Source: examples/todos-server/README.md