todo-mcp-server

A Todo REST API built with Express + Drizzle ORM + SQLite. The MCP server is an add-on mounted at /mcp, allowing AI editors (Cursor, VS Code Copilot, Claude Code, etc.) to query and manage your todos directly from chat.

What makes this interesting: the REST API and the MCP server share the same database layer. Add a todo from the UI and your AI editor sees it instantly — no sync, no duplication.

---

Stack

Layer	Tech
Runtime	Node.js + TypeScript
API	Express 5
ORM	Drizzle ORM
Database	SQLite (via better-sqlite3)
MCP	@modelcontextprotocol/sdk (Streamable HTTP)
Tests	Vitest + Supertest
DB UI	Drizzle Studio

---

Setup

npm install
npm run build
npm start

Server starts on http://localhost:3001.

Environment variables

Variable	Default	Description
PORT	3001	HTTP port
DB_PATH	./todos.db	SQLite database file path

---

REST API

Base URL: http://localhost:3001/api/todos

Endpoints

GET    /api/todos                  List all todos
GET    /api/todos?filter=active    Filter: active | completed | all
GET    /api/todos/:id              Get a single todo
POST   /api/todos                  Create a todo
PATCH  /api/todos/:id              Update title / description / completed
PATCH  /api/todos/:id/complete     Mark as completed (convenience)
DELETE /api/todos/:id              Delete a todo

GET    /health                     Health check

Request / Response shapes

Create todo

POST /api/todos
Content-Type: application/json

{ "title": "Buy milk", "description": "From the corner store" }

{
  "data": {
    "id": "m1k3abc",
    "title": "Buy milk",
    "description": "From the corner store",
    "completed": false,
    "createdAt": "2026-04-04T12:00:00.000Z",
    "updatedAt": "2026-04-04T12:00:00.000Z"
  }
}

List todos

{
  "data": [ { "id": "...", "title": "...", "completed": false, ... } ],
  "count": 1
}

Error response

{ "error": "title is required" }

---

MCP Server

The MCP server is mounted at /mcp on the same port as the REST API. It uses the Streamable HTTP transport (stateful sessions).

Tools available

Tool	Description
list_todos	List todos, optional filter: all|active|completed
get_todo	Get details by id
add_todo	Create with title + optional description
complete_todo	Mark as done by id
update_todo	Update title / description by id
delete_todo	Delete by id

Resources

URI	Description
todos://all	All todos as JSON
todos://active	Active todos as JSON

---

Connecting to AI editors

The server must be running before the editor connects.

Cursor

Create ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "todo": {
      "url": "http://localhost:3001/mcp"
    }
  }
}

VS Code (GitHub Copilot)

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "todo": {
      "type": "http",
      "url": "http://localhost:3001/mcp"
    }
  }
}

Or add to User Settings (settings.json):

{
  "mcp": {
    "servers": {
      "todo": {
        "type": "http",
        "url": "http://localhost:3001/mcp"
      }
    }
  }
}

Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "todo": {
      "type": "http",
      "url": "http://localhost:3001/mcp"
    }
  }
}

Or run in the Claude Code terminal:

claude mcp add --transport http todo http://localhost:3001/mcp

Windsurf

Create ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "todo": {
      "serverUrl": "http://localhost:3001/mcp"
    }
  }
}

---

Database UI (Drizzle Studio)

npm run studio

Opens a visual SQLite browser at https://local.drizzle.studio. You can view, edit, insert, and delete rows directly.

---

Tests

npm test          # run once
npm run test:watch  # watch mode

Tests use an in-memory SQLite database — no test database setup needed.

File	What it covers
tests/api.test.ts	All REST endpoints (Supertest)
tests/mcp.test.ts	All MCP tools and resources (InMemoryTransport)

---

Project structure

src/
  db/
    schema.ts             Drizzle table schema
    client.ts             SQLite + Drizzle setup
  repository/
    todo.repository.ts    CRUD data access layer
  api/
    app.ts                Express app factory
    routes/todos.ts       /api/todos router
    middleware/error.ts   Error handler
  mcp/
    tools.ts              MCP tool definitions (JSON schema)
    server.ts             MCP Server factory
  index.ts                HTTP server entry point
tests/
  api.test.ts
  mcp.test.ts
drizzle.config.ts
vitest.config.ts

---

How MCP Works

The problem MCP solves

Without MCP, an AI assistant in your editor (Copilot, Cursor, Claude) only knows what you show it — open files, pasted text, maybe your repo. It has no connection to the outside world.

With MCP, the AI can call your server during a conversation and get real data or trigger real actions.

Ask Cursor "what are my open todos?" and it will actually query your database and tell you. Ask it to "mark the Buy milk todo as done" and it will. This is MCP.

What MCP actually is

MCP (Model Context Protocol) is an open standard created by Anthropic. It defines a common language between:

• MCP Clients — AI editors (Cursor, VS Code Copilot, Claude Code, Windsurf)
• MCP Servers — your code, exposing capabilities the AI can use

The protocol defines how a client discovers what a server can do, and how it calls those capabilities. Think of it like REST, but designed to be consumed by an AI model rather than a human-built app.

The flow, step by step

You type in editor chat:
  "What todos do I have?"
        │
        ▼
AI Model (Copilot / Cursor / Claude)
  - has a list of available tools from your MCP server
  - decides list_todos is relevant
  - decides to call it
        │
        ▼
MCP Client (inside the editor)
  - sends the request to your server
  - POST http://localhost:3001/mcp
  - body: { method: "tools/call", name: "list_todos", arguments: {} }
        │
        ▼
Your MCP Server (src/mcp/server.ts)
  - receives the call
  - runs: repo.findAll()
  - queries SQLite
        │
        ▼
Response travels back up through the same chain
        │
        ▼
AI model reads the result and answers:
  "You have 3 todos: Buy milk, Fix the login bug, Write tests."

The user never sees any of the middle steps. It feels like the AI just knows.

How this repo is structured around it

The MCP server is not the whole app — it is an add-on layer over an existing API.

SQLite database
      │
      ▼
TodoRepository              ← single source of truth (src/repository/)
      │
      ├──────────────────────────────────┐
      ▼                                  ▼
REST API  (/api/todos)         MCP Server  (/mcp)
src/api/                       src/mcp/
      │                                  │
      ▼                                  ▼
Browser / frontend             AI editors
(humans use this)              (Copilot, Cursor, Claude use this)

The same TodoRepository powers both. The data never duplicates. The only difference is the interface on top.

Tools vs Resources

MCP exposes two types of things:

Tools — actions the AI can invoke. A tool is a function the AI calls when it decides the tool is relevant. Each tool has a name, a description (plain English the AI reads to decide when to use it), and an input schema.

{
  name: "add_todo",
  description: "Create a new todo item.",
  inputSchema: {
    type: "object",
    properties: {
      title: { type: "string", description: "Short title for the todo" },
      description: { type: "string", description: "Optional longer description" },
    },
    required: ["title"],
  },
}

The description is not documentation for humans — it is the signal the AI uses to decide whether and how to call the tool. Good descriptions = better AI decisions.

Resources — read-only data the AI can fetch, identified by a URI.

todos://all     →  all todos as a JSON array
todos://active  →  only active todos as a JSON array

The session handshake

MCP over HTTP is stateful. Before any tool can be called, a session must be established:

1.  Client  →  initialize
              { protocolVersion, clientInfo, capabilities }

2.  Server  →  200 OK
              mcp-session-id: <uuid>   ← in response header
              { protocolVersion, serverInfo, capabilities }

3.  Client  →  notifications/initialized
              (tells the server "I received your response, I'm ready")

4.  Client  →  tools/list
              (asks "what tools do you have?")

5.  Server  →  { tools: [...] }
              (returns all tool definitions with descriptions and schemas)

6+. Client  →  tools/call  (repeated as needed during the conversation)
    Server  →  { content: [{ type: "text", text: "..." }] }

The session ID from step 2 must be sent as the mcp-session-id header on every subsequent request. In this repo, sessions are tracked in a Map in src/index.ts.

Why the response format looks different from REST

REST returns whatever JSON shape you want. MCP tool responses always follow this shape:

{
  "content": [
    { "type": "text", "text": "Your result here" }
  ]
}

The AI model reads the text field and incorporates it into its reply to the user. You never return raw JSON from a tool — you return text the AI can reason about.

What the AI does with tool descriptions

When an editor connects, it calls tools/list once and gets back all your tool definitions. From that point on, when a user asks something, the model decides on its own:

• Does any tool seem relevant to this request?
• If yes, what arguments should I pass based on what the user said?
• Do I need to call multiple tools in sequence?

You never hardcode "call list_todos when the user asks about todos." The model figures it out from the description you wrote.

Concept glossary

Concept	What it is
MCP	A protocol for AI models to call external tools and read data
MCP Server	Your code, exposing tools and resources the AI can use
MCP Client	The editor (Cursor, Copilot, Claude) that connects to your server
Tool	A function the AI can call — has a name, description, and input schema
Resource	Read-only data the AI can fetch, identified by a URI
Session	One connected editor instance, tracked by a session ID
tools/list	The handshake step where the AI discovers what your server can do
tools/call	The AI actually invoking one of your tools
Description	Plain English the AI reads to decide when and how to use a tool