The MCP Handbook

The MCP Handbook – Table of Contents

A practical introduction to the Model Context Protocol
Author: Michael Lechner | Version: 2.2.0 (October 2026)
License: Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0)

Welcome to The MCP Handbook. This guide takes developers, architects, and AI engineers from the core fundamentals to production-grade agentic environments based on the official Model Context Protocol specification (as of October 2026).

📚 Chapter Overview

Part I: Fundamentals & Core Protocol

  1. Chapter 1: Introduction
    USB-C for AI models. Why build custom servers? The secure database gatekeeper, "Compute instead of reasoning" (wollmilchsau), and the Living Document philosophy.
  2. Chapter 2: How LLMs Communicate
    Prompts, message roles (system, user, assistant, tool), Function Calling, and JSON-RPC 2.0 as the backbone.
  3. Chapter 3: Minimal MCP (Stdio)
    Your first MCP server built from scratch in Go over standard input/output (stdio).
  4. Chapter 4: Tools - The Hands of the Model
    Invoking actions, CPU offloading, strategic error handling (SEP-1303), and Tool Annotations (readOnlyHint, destructiveHint, idempotentHint).
  5. Chapter 5: Resources - The Memory of the Model
    URIs, static vs. dynamic templates, real-time subscriptions, and Workspace Roots (roots/list).
  6. Chapter 6: Prompts - Instructions and Templates
    Reusable prompt templates, argument validation, and context injection.
  7. Chapter 7: The Power of Combination - Multi-Server Orchestration
    Running multiple specialized servers concurrently and combining workflows.

Part II: Scaling, Data & Model Boundaries

  1. Chapter 8: The Tool Trap - Problems with Too Many Tools
    Context overload, selection noise, and Progressive Disclosure.
  2. Chapter 9: Return Values - From Text to Structured Data
    JSON schemas for tool returns, strongly typed responses, and hallucination reduction.
  3. Chapter 10: Binary Data - When the AI Sends Images
    Base64 payloads, image generation, diagrams, and MIME types in MCP.
  4. Chapter 11: Real-Time Feedback & Cancellation - Interactive Tools
    Progress notifications (notifications/progress), cancellation tokens, and streaming.
  5. Chapter 12: The Limits of AI - Model Constraints and Context Overflow
    Token budgets, context window constraints, and graceful fallbacks.
  6. Chapter 13: The Artifact Pattern - Bridging Model Limits and User Experience
    Efficiently decoupling LLM context from rich user interfaces.

Part III: Quality Assurance, Production & Security

  1. Chapter 14: Quality Assurance – The Server Inspector & Quality Scoring
    Interactive debugging with the MCP Inspector and automated testing with `mcp-tester` (0–100 scoring, early spec-drift detection).
  2. Chapter 15: Automation & CI/CD
    Headless pipeline testing, regression testing, and deployment workflows.
  3. Chapter 16: Transports in Detail – stdio and Streamable HTTP
    Stateless MCP, one endpoint with POST, mandatory headers, subscriptions/listen, Origin validation, HTTP/2 and proxies, mcp-tester http-check.
  4. Chapter 17: Security & Authentication - OAuth 2.1 for Remote Servers
    OAuth 2.1 with PKCE, Protected Resource Metadata, Client ID Metadata Documents, audience validation, scope step-up, no token passthrough, Indirect Prompt Injection (IPI), and production security checklist.

Part IV: Agentic Protocols & Extensions

  1. Chapter 18: Extensions - Notifications (Push Messages)
    One-way messages from server to client for asynchronous event signaling.
  2. Chapter 19: Tasks – Long-Running Operations & Asynchrony (SEP-2663)
    The 2026-07-28 Tasks extension: state machine, tasks/get/tasks/update/tasks/cancel, mid-flight input via inputRequests, a task store in Go – and tasks as a shell for sub-agents.
  3. Chapter 20: Agentic Servers & Sampling - When the Server Asks the AI
    Sampling (deprecated) via MRTR, the move to the server's own model – and the server as a sub-agent: a code-review guard running a local Qwen model.
  4. Chapter 21: User Queries & Elicitation - Human-in-the-Loop
    Asking the human: form and URL mode, the multi round-trip request flow, and a tested Go example with a signed requestState.
  5. Chapter 22: Choosing the Right Programming Language for MCP Servers
    Go, TypeScript/JavaScript, and Python in architectural comparison.
  6. Chapter 23: Agent Skills – Modular Expert Knowledge & "Skills over MCP"
    Local skills (.agents/skills/) vs. the official wire extension io.modelcontextprotocol/skills (SEP-2640), skills/list, and Progressive Disclosure.

📖 Appendix

Deutsche Version verfügbar unter book/de/chapters/.

Licence: CC BY-NC 4.0