# DD-22 — MCP: Building Production Tool Servers

**Course**: Master Course · **Deep-Dive**: DD-22 · **Duration**: 50 min · **Level**: Senior engineer · **Status**: Complete
**Pillar**: Deep-Dives

> Pi's 4 tools are hand-coded. An MCP server externalizes tool definitions into a discoverable, versioned, independently-deployable service. This is the difference between a personal harness and a platform.

## Artifacts

| # | Artifact | File | Purpose |
| --- | --- | --- | --- |
| 01 | Teaching Document | [01-teaching-document.md](01-teaching-document.md) | ~3,400 words. 7 sub-sections: thesis, protocol (JSON-RPC + transports + primitives), lifecycle, tool definitions (JSON Schema validation boundary), production TypeScript server, registry/discovery/version drift, resources/subscriptions, production patterns + C4 connection. Anti-patterns, key terms, references. |
| 02 | Diagrams | [02-diagrams.md](02-diagrams.md) | 6 Mermaid diagrams: Pi-registry vs MCP-server, three trust boundaries, server lifecycle, capability negotiation intersection, validation boundary (3 error classes), production failure modes. Design-system colors. |
| 03 | Slide Deck | [03-slide-deck.html](03-slide-deck.html) | 10-slide reveal.js deck. Dark theme, accent #5eead4. Covers thesis, three primitives, trust boundaries, lifecycle, capability negotiation, validation boundary, three error classes, production operations, platform turn. |
| 04 | Teaching Script | [04-teaching-script.md](04-teaching-script.md) | ~2,700 words, verbatim transcript with [SLIDE N] cues across 10 slides. |
| 05 | Flashcards | [05-flashcards.tsv](05-flashcards.tsv) | 22 cards. Header + 22 Q/A with tags (c1::dd22::recall/application/analysis). |
| 06 | Exam | [06-exam.json](06-exam.json) | 15 questions. Bloom distribution: 3 recall / 6 application / 6 analysis. 70% pass. Rationale per question. |
| 07 | Lab Specification | [07-lab-spec.md](07-lab-spec.md) | Build a TypeScript MCP server: two tools, JSON Schema validation, three-class error model, graceful shutdown, test client exercising the full lifecycle. stdout corruption demo, capability negotiation experiment, 5 stretch goals. |
| 08 | Module Web Page | [08-module-web-page.html](08-module-web-page.html) | Single-file HTML hub: hero, lede, claims, objectives, artifacts, key terms, navigation. |
| -- | Metadata | [module-meta.json](module-meta.json) | Concept-deep-dive shape: claims, objectives, subsections, navigation (prev=DD-21, next=DD-23). |

## Sub-sections

- **DD-22.1 The Protocol: JSON-RPC, Transports, and the Three Primitives** (8 min) — The envelope (JSON-RPC 2.0: request, response, notification). The two transports (stdio for local, HTTP+SSE for remote). The three primitives (tools: model-invoked; resources: user/client-read; prompts: user-invoked) and why each maps to a different trust boundary.
- **DD-22.2 The Lifecycle: Initialization, Negotiation, and the Message Loop** (8 min) — The four phases: initialize (exchange versions + capabilities), initialized notification (handshake complete), message loop (tools/list, tools/call, resources/read), graceful shutdown (drain + close + exit). Why skipping initialization is the most common integration bug.
- **DD-22.3 Tool Definitions: JSON Schema as the Validation Boundary** (6 min) — A tool is name + description + JSON Schema input. additionalProperties: false as a security control. The server re-validates on every call — never trust the model or the client.
- **DD-22.4 A Production MCP Server in TypeScript** (10 min) — Real, compilable code against the official SDK. Five production details: additionalProperties, validation-at-boundary, three error classes, stderr-only logging, SIGTERM handling.
- **DD-22.5 Registry, Discovery, and Version Drift** (6 min) — Static config vs dynamic registry (the line is ~5-8 servers). Version drift as the hard problem. Namespacing by server, pinning versions, treating schema changes as breaking.
- **DD-22.6 Resources, Subscriptions, and the Flood Risk** (6 min) — The subscription capability and its failure mode: the flood. Subscribe narrowly, debounce on the server, unsubscribe aggressively.
- **DD-22.7 Production Patterns and the C4 Connection** (6 min) — Connection pooling, health checks, rate limiting, idempotency, structured logging. The bridge to Course 4 Module E07 (MCP-at-scale: registry-as-service, multi-tenancy, policy, audit).

## Load-bearing claims

- **The platform turn.** Pi's four tools are compiled-in function references. MCP externalizes tools into discoverable, versioned, independently-deployable services. This is the structural difference between a personal harness and a platform.
- **Three primitives, three trust boundaries.** Tools (model-initiated, untrusted, schema-validated), resources (user/client-initiated, semi-trusted), prompts (user-initiated, server-authored, trusted). Confusing them is a security bug — exposing as a tool what should be a resource lets the model act autonomously when it shouldn't.
- **Capability negotiation is the contract.** The initialize handshake exchanges what both sides support. The session uses only the intersection. This is what lets a client built once work against any server — present, future, or third-party.
- **JSON Schema is the validation boundary, not documentation.** additionalProperties: false is a security control. The server re-validates on every call. Trusting the model or client to validate is an unenforced boundary.
- **Three error classes, three recovery paths.** Unknown tool, validation failure, execution failure — each must return a distinguishable payload. Conflating them produces a confused model loop.

## Learning objectives

1. State the MCP thesis and explain why externalizing tools is the difference between a personal harness and a platform.
2. Describe the three primitives, two transports, and the JSON-RPC 2.0 envelope.
3. Walk the full server lifecycle: initialization, capability negotiation, message loop, graceful shutdown.
4. Write a JSON Schema for tool input and explain why additionalProperties: false is a security control.
5. Implement a production MCP server in TypeScript with validation, error handling, and graceful shutdown.
6. Explain the registry/discovery pattern and how capability negotiation enables version-drift tolerance.
7. Diagnose the four production failure modes: stdout corruption, schema drift, subscription flood, no graceful shutdown.

## Navigation

- Previous: [DD-21 — Tau](../dd-21-tau/)
- Next: [DD-23 — DeerFlow](../dd-23-deerflow/)
- Up: [Course 1 — Master Course](../../)