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.

---

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-minimal/

SDK Comparison

	TypeScript	Python	Go	Rust	Java	C#	Kotlin
Package	@modelcontextprotocol/sdk	mcp	mcp-go	rmcp	io.modelcontextprotocol:sdk	ModelContextProtocol	io.modelcontextprotocol:kotlin-sdk-server
Server setup	new McpServer(...)	FastMCP(...)	server.NewMCPServer(...)	impl Server trait	McpServer.sync(...)	builder.Services.AddMcpServer()	Server(Implementation(...), ServerOptions(...))
Tool definition	server.tool()	@mcp.tool()	s.AddTool()	fn list_tools()	.tool(new SyncToolSpec)	[McpServerTool]	server.addTool(...)
Transport	StdioServerTransport	mcp.run()	server.ServeStdio()	stdio()	StdioServerTransportProvider	.WithStdioServerTransport()	StdioServerTransport(...)
Maturity	Most mature	Rapidly improving	Active	Early	Active (Spring AI)	Official, fast-moving	Official, fast-moving
Best for	Production servers	Quick prototypes	Fast binaries	Performance-critical	Enterprise / Spring	.NET services	Kotlin / JVM teams

Roadmap

• Quick Start guides (TypeScript + Python)
• Core concept explanations (Tools, Resources, Prompts)
• Architecture patterns guide
• Security & authentication deep dive
• Testing framework and helpers
• Production deployment guide (Docker, monitoring)
• Performance optimization guide
• Video walkthroughs
• Interactive playground

See the full roadmap →

Contributing

This handbook is a community effort. We welcome contributions of all sizes.

Quick ways to contribute:

• Fix a typo or improve an explanation
• Add a new example server
• Share a pattern you've discovered
• Translate a guide to another language

See CONTRIBUTING.md for guidelines.

License

MIT License. See LICENSE for details.

---

Found this useful? Give it a ⭐ to help other developers find it.

Built by the community, for the community.

Report an Issue · Suggest a Topic · Contribute