MCP Server Example — Tasks API

A production-ready Model Context Protocol (MCP) server in TypeScript that exposes a Tasks management API to LLM clients like Claude Desktop, Claude Code, or custom AI agents. Ships with a Dockerized PostgreSQL database and one-command setup.

Built as a reference implementation of a real-world MCP server with all three core primitives — tools, resources, and prompts — plus a clean architecture that scales beyond toy examples.

---

What this demonstrates

• ✅ MCP server with 5 tools, 2 resources, and 2 prompts
• ✅ Real database (PostgreSQL + Prisma) — not in-memory data
• ✅ Clean modular structure (one file per tool, easy to extend)
• ✅ Dockerized infrastructure — no local Postgres setup needed
• ✅ One-command bootstrap (bash scripts/setup.sh)
• ✅ MCP Inspector and Claude Desktop integration documented

Quick video demostration

Demo.mp4

Quick start

git clone https://github.com/YOUR_USERNAME/mcp-server-example.git
cd mcp-server-example
bash scripts/setup.sh

That's it. The script will:

1. Verify Docker and Node.js 20+
2. Start PostgreSQL via Docker Compose
3. Install dependencies, run migrations, seed the database
4. Build the TypeScript project

When it finishes, run npm run inspector to test the server in a browser, or follow docs/claude-desktop-setup.md to connect it to Claude Desktop.

What's inside

Tools (actions the LLM can invoke)

Tool	Description
list_tasks	List tasks with filters by status, priority, or project
create_task	Create a new task in an existing project
update_task	Update any field of an existing task
delete_task	Delete a task permanently
search_tasks	Full-text search across task title and description

Resources (read-only context the LLM can fetch)

URI	Description
tasks://projects	All projects with task counts and status breakdown
tasks://dashboard	High-level stats: totals by status, priority, overdue tasks

Prompts (reusable templates exposed as slash commands)

Prompt	Description
standup_report	Generate a daily standup report from current tasks
prioritize_backlog	Analyze pending tasks and suggest prioritization

Architecture

graph LR
    Client[Claude Desktop / Inspector]
    Server[MCP Server<br/>Node.js + TypeScript]
    DB[(PostgreSQL<br/>via Docker)]

    Client -- stdio JSON-RPC --> Server
    Server -- Prisma ORM --> DB

Loading

See docs/architecture.md for the full architecture, data model, and key design decisions.

Project structure

mcp-server-example/
├── docker-compose.yml      # PostgreSQL + persistent volume
├── Dockerfile              # Multi-stage build for the server
├── prisma/
│   ├── schema.prisma       # Project + Task models
│   └── seed.ts             # Example data
├── src/
│   ├── index.ts            # Entry point (stdio transport)
│   ├── server.ts           # MCP server setup
│   ├── db.ts               # Prisma singleton
│   ├── tools/              # One file per tool
│   ├── resources/          # MCP resources
│   └── prompts/            # MCP prompts
├── docs/
│   ├── architecture.md
│   └── claude-desktop-setup.md
└── scripts/
    └── setup.sh            # One-command setup

Stack

• Language: TypeScript (Node.js 20)
• MCP SDK: @modelcontextprotocol/sdk
• Database: PostgreSQL 16 (Alpine, via Docker)
• ORM: Prisma 6
• Validation: Zod
• Infra: Docker Compose

Manual commands

If you prefer not to use the setup script:

# Start the database
docker compose up -d

# Install deps and prepare DB
npm install
npx prisma generate
npx prisma db push
npm run db:seed

# Build and run
npm run build
npm start          # via stdio (for MCP clients)
npm run dev        # watch mode
npm run inspector  # browser-based MCP testing UI

Example interactions

Once connected to Claude Desktop, you can have conversations like:

You: What urgent tasks are overdue?

Claude: Let me check. (calls tasks://dashboard, then list_tasks with priority filter, then synthesizes a response)

You: Add a task to implement caching in the AI Integration project, high priority, due next Friday.

Claude: (calls create_task with the right parameters)

Why MCP?

The Model Context Protocol is an open standard from Anthropic for connecting LLMs to external tools and data sources. Unlike vendor-specific tool calling, MCP servers work with any compatible client (Claude Desktop, Claude Code, custom agents, IDE plugins, etc.) — write once, use everywhere.

This project shows what a real MCP server looks like beyond the "hello world" examples: with a real database, modular structure, and the three primitive types (tools/resources/prompts) working together.

Roadmap

• Add Streamable HTTP transport for remote deployment
• Add OAuth authentication for multi-tenant scenarios
• Add evals using Promptfoo
• Add observability via Langfuse
• Add structured output validation for tool responses

License

MIT

---

Built by Isidro González — AI Engineer specialized in backend automation systems powered by LLMs and agents.