Task Manager — MCP Server + Next.js

A small but complete example that demonstrates every core Model Context Protocol (MCP) concept, wired to a Next.js web app that shares the same data.

An AI client (e.g. Claude Desktop) talks to the MCP server to read and change tasks; the Next.js UI shows those same tasks and updates live.

┌────────────────┐   MCP (stdio / JSON-RPC)   ┌───────────────────────┐
│  AI client     │ ─────────────────────────► │  mcp-server/server.ts │
│ (Claude etc.)  │   tools · resources ·      │  Resources / Tools /  │
└────────────────┘   prompts                  │  Prompts / Transport  │
                                              └──────────┬────────────┘
                                                         │  reads/writes
                                                         ▼
                                              ┌───────────────────────┐
┌────────────────┐    HTTP / REST             │   lib/store.ts        │
│  Web browser   │ ─────────────────────────► │   data/tasks.json     │
│ (Next.js UI)   │   /api/tasks               │  (shared file store)  │
└────────────────┘                            └───────────────────────┘

MCP concepts demonstrated

Concept	Where	Examples
Resources	mcp-server/server.ts	tasks://all, tasks://stats, tasks://{id} (templated)
Tools	mcp-server/server.ts	create_task, update_task, complete_task, delete_task, search_tasks
Prompts	mcp-server/server.ts	summarize_tasks, daily_plan (parameterized)
Transport	mcp-server/server.ts	stdio (Claude Desktop compatible)

Project structure

lib/store.ts                # Shared, file-backed task store (single source of truth)
mcp-server/server.ts        # The MCP server: resources + tools + prompts + stdio
mcp-server/smoke-test.ts    # End-to-end MCP client test (uses the official SDK Client)
app/page.tsx                # Task manager web UI
app/api/tasks/route.ts      # REST: GET (list/search) + POST (create)
app/api/tasks/[id]/route.ts # REST: GET / PATCH / DELETE one task
claude_desktop_config.json  # Example config to connect Claude Desktop

Run it

1. The web app

npm run dev
# open http://localhost:3000

2. The MCP server (standalone)

npm run mcp            # runs the server over stdio
npm run mcp:inspect    # opens the MCP Inspector UI to click through tools/resources/prompts

3. End-to-end smoke test

npx tsx mcp-server/smoke-test.ts

Exercises the full MCP surface: lists tools/resources/templates/prompts, calls a tool, reads resources, and fetches a prompt.

Connect to Claude Desktop

Add the mcpServers block from claude_desktop_config.json to your Claude Desktop config (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json), adjusting cwd to this project's absolute path. Restart Claude Desktop, then ask it to "create a task" or "summarize my tasks" — the changes appear in the web UI too.

How the two sides stay in sync

Both the MCP server process and the Next.js API import the same lib/store.ts, which persists to data/tasks.json. Anything the AI does through MCP is immediately visible in the browser (the UI polls every 3s), and vice-versa — verified across separate processes.