Todo MCP

Demo project for learning Model Context Protocol (MCP).

A small Next.js todo app exposes the same list as an MCP server over Streamable HTTP. Use it to see how agents call tools against a real app — either on your machine or against a hosted deployment.

What you get

• Web UI at / — add, complete, and purge todos
• MCP server at /api/mcp — tools that operate on the same shared store

Tool	What it does
list_todos	List todos (optional filter: active, completed, purged)
add_todo	Create an active todo
set_todo_completed	Mark completed or return to active
delete_todo	Move a todo to purged (not restored)

Storage

• Local (no env): in-memory store. UI and MCP share it in one Node process. Resets on restart.
• Local or Vercel (with KV env): Vercel KV via @upstash/redis. UI and MCP stay in sync across serverless instances.
• Vercel without KV env: fails fast with a clear config error.

Copy .env.example to .env.local when you want KV locally:

KV_REST_API_URL=
KV_REST_API_TOKEN=

Prerequisites

• Node.js 20+
• An MCP client (e.g. Cursor)

npm install

Option A — Hosted MCP (default)

This repo’s .cursor/mcp.json points at the deployed demo:

{
  "mcpServers": {
    "todo-mcp": {
      "type": "http",
      "url": "https://todo-mcp-playground.vercel.app/api/mcp"
    }
  }
}

Enable / refresh todo-mcp in Cursor MCP settings, then ask the agent to list or add todos. Open https://todo-mcp-playground.vercel.app/ — the UI polls every few seconds, so MCP changes show up without a hard refresh.

Hosted deploys need a KV database connected to the Vercel project so KV_REST_API_URL and KV_REST_API_TOKEN are injected.

Before exposing private data: add auth. The demo has none.

Option B — Run locally

1. Start the app:

npm run dev

2. Open http://localhost:3000 for the UI.

3. Point your MCP client at the local server (override .cursor/mcp.json or add a second entry):

{
  "mcpServers": {
    "todo-local": {
      "type": "http",
      "url": "http://localhost:3000/api/mcp"
    }
  }
}

4. Enable / refresh todo-local in Cursor MCP settings, then ask the agent to list or add todos.

No KV env required. Optional: set the vars from .env.example to exercise the same Redis path as production.

Project layout

app/              # Next.js UI + /api/mcp route
components/       # Todo UI
lib/todos.ts      # In-memory local store + Vercel KV persistence
lib/redis.ts      # KV client (null locally when env is unset)
mcp/server.ts     # Tool registration (mcp-handler)
.cursor/mcp.json  # Cursor MCP config (hosted by default)

More MCP detail: mcp/README.md.

Learn by doing

1. Use the hosted MCP config, ask the agent to add a todo, watch it appear on the site.
2. Or run locally, open the UI, add a todo, then ask the agent to list it.
3. Deploy your own copy with KV connected, switch the MCP URL, confirm tools still work.

That loop is the point of the demo: MCP tools as another interface to your app.