<div align="center"> <img src="assets/mcp-handbook-cover.png" alt="MCP Handbook cover illustration" width="560" />

The MCP Handbook

The missing developer guide for the Model Context Protocol

English | 中文 (README + Guides 01-03)

84,000+ developers starred an MCP server list. Zero had a guide on how to actually build one.

Until now.

Get Started | Guides | Examples | Templates | Contribute

Verified in CI: Every example and starter template is validated on GitHub Actions.

</div>

---

[!TIP] New to MCP? Start with the Quick Start below — you'll have a working server in under 5 minutes.

Already building? Jump to Architecture Patterns for production-ready designs.

Why This Exists

MCP (Model Context Protocol) is the open standard that connects AI assistants to your tools and data. It's backed by Anthropic, adopted by VS Code, Cursor, Claude Code, and dozens of AI tools.

The problem? The ecosystem has 1,000+ MCP servers but almost no guidance on how to build them well. Developers are reverse-engineering patterns from source code, rediscovering the same pitfalls, and shipping insecure servers to production.

This handbook fixes that. It's the guide we wished existed when we started building MCP servers — from "hello world" to production, covering patterns, security, testing, and real-world architecture.

[!NOTE] This is a community-driven project. If something is unclear, outdated, or missing — open an issue or submit a PR. Every contribution helps.

What You'll Learn

You are here
    │
    ├── 🟢 Beginner ──────── What is MCP? Build your first server in 10 minutes
    │
    ├── 🟡 Intermediate ──── Architecture patterns, testing, error handling
    │
    ├── 🔴 Advanced ───────── Security hardening, production deployment, performance
    │
    └── 📋 Reference ──────── Templates, checklists, SDK comparison

Quick Start

Build a working MCP server in under 5 minutes.

TypeScript

# Create a new project
mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod

// server.ts — A complete MCP server in 30 lines
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "my-first-server",
  version: "1.0.0",
});

// Add a tool that AI assistants can call
server.tool(
  "greet",
  "Generate a greeting for someone",
  { name: z.string().describe("Name of the person to greet") },
  async ({ name }) => ({
    content: [{ type: "text", text: `Hello, ${name}! Welcome to MCP.` }],
  })
);

// Connect via stdio transport
const transport = new StdioServerTransport();
await server.connect(transport);

# Test it instantly with the MCP Inspector
npx @modelcontextprotocol/inspector node server.ts

Python

# Create a new project
mkdir my-mcp-server && cd my-mcp-server
pip install mcp

# server.py — A complete MCP server in 20 lines
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-first-server")

@mcp.tool()
def greet(name: str) -> str:
    """Generate a greeting for someone."""
    return f"Hello, {name}! Welcome to MCP."

if __name__ == "__main__":
    mcp.run()

# Test it instantly with the MCP Inspector
npx @modelcontextprotocol/inspector python server.py

Next step: Connect your server to Claude Desktop, VS Code, or Cursor →

Guides

| # | Guide | Level | What You'll Learn | |---|-------|-------|-------------------| | 01 | Getting Started | Beginner | MCP concepts, your first server, connecting to clients | | 02 | Tools, Resources & Prompts | Beginner | The three building blocks of MCP servers | | 03 | Architecture Patterns | Intermediate | Server design patterns for common use cases | | 04 | Error Handling | Intermediate | Graceful failures, retries, and user-friendly errors | | 05 | Testing MCP Servers | Intermediate | Test harness, mocking, property-based testing, CI/CD pipelines | | 06 | Security & Auth | Advanced | OAuth, RBAC, prompt injection defense, audit logging, SSRF prevention | | 07 | Production Deployment | Advanced | Docker, monitoring, scaling, and reliability | | 08 | Performance & Optimization | Advanced | Caching, pagination, streaming large datasets | | 09 | Debugging | Intermediate | Inspector, logging, common issues and fixes | | 10 | Advanced Topics | Advanced | Sampling, elicitation, OAuth, HTTP transport, subscriptions |

Examples

Real-world MCP servers you can learn from and adapt. Each includes a README, complete source code, and instructions for connecting to AI clients.

TypeScript

| Example | What It Demonstrates | |---------|---------------------| | Database Explorer | SQL queries as tools, schema as resources, read-only enforcement | | REST API Wrapper | Turning any REST API into an MCP server (HackerNews) |

Python

| Example | What It Demonstrates | |---------|---------------------| | File Search | Sandboxed file access with content search | | Web Scraper | Fetching and parsing web content (stdlib only) |

Go

| Example | What It Demonstrates | |---------|---------------------| | Hello Server | Tools and resources with mcp-go SDK |

Rust

| Example | What It Demonstrates | |---------|---------------------| | Hello Server | Trait-based server with rmcp SDK |

Java

| Example | What It Demonstrates | |---------|---------------------| | Hello Server | Builder-based server with official Java SDK |

C#

| Example | What It Demonstrates | |---------|---------------------| | Hello Server | Hosted server with official C# SDK and attribute-based tools | | REST API Wrapper | Hacker News API wrapper with HttpClient injection and official C# SDK |

Kotlin

| Example | What It Demonstrates | |---------|---------------------| | Hello Server | Coroutine-friendly stdio server with the official Kotlin SDK | | REST API Wrapper | Hacker News API wrapper with Ktor client and official Kotlin SDK |

Language Matrix

Use this table to pick the best starting point for your stack. Today the deepest lanes are TypeScript and Python; the fastest-growing official SDK lanes in this repo are C# and Kotlin.

| Pattern | TypeScript | Python | Go | Rust | Java | C# | Kotlin | |---|---|---|---|---|---|---|---| | Minimal / Hello | Minimal Template | Minimal Template | Hello Server | Hello Server | Hello Server | Hello Server | Hello Server | | HTTP / API | REST API Wrapper | Web Scraper | - | - | - | REST API Wrapper | REST API Wrapper | | Database | Database Explorer | - | - | - | - | - | - | | File System | - | File Search | - | - | - | - | - |

Recipes

Quick, copy-paste solutions for common MCP tasks. See the full recipe index →

| Recipe | What It Solves | |--------|---------------| | Environment Config | Load and validate env vars at startup | | Graceful Shutdown | Clean up resources on exit | | Structured Logging | Log to stderr without breaking protocol | | Paginated Results | Return large datasets in pages | | Long-Running Ops | Report progress on slow tasks | | Confirmation Pattern | Two-step tools for dangerous operations | | Batch Operations | Handle partial failures in bulk ops | | REST API Client | Fetch wrapper with auth, retries, timeouts | | Database Connection | Connection pooling and lifecycle | | Caching Layer | In-memory TTL cache | | Rate Limiter | Throttle external API calls | | Input Sanitization | Validate all tool inputs | | Path Sandboxing | Restrict file access to allowed dirs |

Templates

Copy-paste starters to skip the boilerplate.

| Template | Language | Use Case | |----------|----------|----------| | Minimal Server | TypeScript | Bare-bones starting point | | Minimal Server | Python | Bare-bones starting point |

Patterns at a Glance

Quick reference for common decisions:

When to use Tools vs Resources vs Prompts

Use TOOLS when:          Use RESOURCES when:       Use PROMPTS when:
├─ Action has side       ├─ Exposing read-only     ├─ Providing reusable
│  effects (write,       │  data (files, configs,   │  prompt templates
│  send, create)         │  database records)       │  with parameters
├─ Needs input params    ├─ Data has a natural URI  ├─ Guiding the AI's
│  at call time          │  (file://, db://)        │  approach to a task
└─ Returns a result      └─ Client may cache or     └─ Encoding domain
   of an operation          subscribe to updates       expertise

MCP Server Architecture Decision Tree

What does your server do?
│
├── Wraps an external API?
│   └── Use the API Wrapper pattern → examples/typescript/rest-api-wrapper/
│
├── Exposes a database?
│   └── Use the Database Explorer pattern → examples/typescript/database-explorer/
│
├── Accesses the file system?
│   └── Use the File Access pattern → examples/python/file-search/
│
├── Combines multiple data sources?
│   └── Use the Aggregator pattern → guides/03-architecture-patterns.md
│
└── Something else?
    └── Start with the Minimal template → templates/typescript-minim