Handbook
The practical MCP handbook with production guides, runnable examples, and starter templates across TypeScript, Python, C#, Kotlin, Go, Rust, and Java.
Ask AI about Handbook
Powered by Claude Β· Grounded in docs
I know everything about Handbook. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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.
