{
  "id": "DD-22",
  "title": "MCP: Building Production Tool Servers",
  "pillar": "Deep-Dives",
  "duration": 50,
  "level": "senior",
  "prerequisites": ["Modules 0-12", "DD-01 (Pi)", "DD-11 (OpenAI Agents SDK)"],
  "subtitle": "The wire protocol that turns hardcoded tool registries into discoverable, versioned, independently-deployable services. The platform turn. JSON-RPC 2.0, stdio/HTTP+SSE, tools/resources/prompts, capability negotiation, JSON Schema validation, registry/discovery, production failure modes. With a real TypeScript MCP server.",
  "lede": "A tool is a function the model can call. A tool server is a process that exposes tools, resources, and prompts over a wire protocol — discoverable, versioned, independently deployable. MCP is that wire protocol. This deep-dive builds production tool servers: the lifecycle, the capability negotiation, the schema validation, the registry, and the failure modes that turn a clever integration into a production outage.",
  "claims": [
    "The platform turn. Pi's four tools are compiled-in function references. Adding one means editing source, shipping a build, restarting. MCP externalizes tools into services. A vendor ships a server; the agent discovers it at runtime. This is the structural difference between a personal harness and a platform.",
    "Three primitives, three trust boundaries. Tools (model-initiated, untrusted input, schema-validated). Resources (user/client-initiated, semi-trusted). Prompts (user-initiated, server-authored, trusted). Confusing them — exposing as a tool what should be a resource — is a security bug: the model can now act autonomously when it shouldn't.",
    "Capability negotiation is the contract. The initialize handshake exchanges what both sides support. The session may only use the intersection. A client built once works against every server — present, future, third-party — using whatever subset both offer.",
    "JSON Schema is the validation boundary, not documentation. additionalProperties: false is a security control — it prevents a steered model from injecting unexpected fields (e.g., a hidden bcc on send_email). The server re-validates on every call. Never trust the model or the client to validate.",
    "Three error classes, three recovery paths. Unknown tool (model stops calling), validation failure (model retries with fixed args), execution failure (model retries or reports). Each returns a distinguishable isError payload. Conflating them produces a confused loop.",
    "The four production failure modes: stdout corruption (a console.log on stdio breaks the stream), schema drift (version mismatch across servers), subscription flood (volatile resource drowns the context), no graceful shutdown (orphaned requests and leaked resources). Each has a known fix."
  ],
  "objectives": [
    "State the MCP thesis and explain why externalizing tools is the difference between a personal harness and a platform.",
    "Describe the three primitives (tools, resources, prompts), two transports (stdio, HTTP+SSE), and the JSON-RPC 2.0 envelope.",
    "Walk the full server lifecycle: initialization, capability negotiation, message loop, graceful shutdown.",
    "Write a JSON Schema for tool input and explain why additionalProperties: false is a security control.",
    "Implement a production MCP server in TypeScript with schema validation, three-class error handling, stderr logging, and SIGTERM-driven graceful shutdown.",
    "Explain the registry/discovery pattern and how capability negotiation enables version-drift tolerance.",
    "Diagnose the four production failure modes and name the fix for each."
  ],
  "subsections": [
    {
      "id": "DD-22.1",
      "title": "The Protocol: JSON-RPC, Transports, and the Three Primitives",
      "duration": "8 min",
      "desc": "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."
    },
    {
      "id": "DD-22.2",
      "title": "The Lifecycle: Initialization, Negotiation, and the Message Loop",
      "duration": "8 min",
      "desc": "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."
    },
    {
      "id": "DD-22.3",
      "title": "Tool Definitions: JSON Schema as the Validation Boundary",
      "duration": "6 min",
      "desc": "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."
    },
    {
      "id": "DD-22.4",
      "title": "A Production MCP Server in TypeScript",
      "duration": "10 min",
      "desc": "Real, compilable code against the official SDK. Five production details: additionalProperties in every schema, validation-at-the-boundary, three distinguishable error classes, stderr-only logging, SIGTERM-driven graceful shutdown."
    },
    {
      "id": "DD-22.5",
      "title": "Registry, Discovery, and Version Drift",
      "duration": "6 min",
      "desc": "Static config vs dynamic registry (the line is ~5-8 servers). Version drift as the hard problem. Namespacing tools by server, pinning versions in the registry, treating schema changes as breaking."
    },
    {
      "id": "DD-22.6",
      "title": "Resources, Subscriptions, and the Flood Risk",
      "duration": "6 min",
      "desc": "The subscription capability and its failure mode: the flood. Subscribe narrowly to specific URIs, debounce on the server, unsubscribe aggressively when the model is done."
    },
    {
      "id": "DD-22.7",
      "title": "Production Patterns and the C4 Connection",
      "duration": "6 min",
      "desc": "Connection pooling, health checks (outside the protocol), rate limiting per client, idempotency keys for side-effecting tools, structured logging to stderr. The bridge to Course 4 Module E07 (MCP-at-scale: registry-as-service, multi-tenancy, policy, audit)."
    }
  ],
  "prev": {
    "title": "DD-21 — Tau: The Educational Reference Harness",
    "url": "../dd-21-tau/",
    "label": "Previous"
  },
  "next": {
    "title": "DD-23 — DeerFlow: Deep Research Agent Architecture",
    "url": "../dd-23-deerflow/",
    "label": "Next"
  },
  "course1_index": "../../",
  "nav_code": "DD-22",
  "footer": "Harness Engineering Master Course · Deep-Dives · The Platform Turn",
  "artifact_descs": {
    "01": "Teaching document — 7 sub-sections covering the MCP thesis, the protocol (JSON-RPC 2.0 + stdio/HTTP+SSE + three primitives), the server lifecycle, JSON Schema as validation boundary, a full production TypeScript server, registry/discovery/version drift, resources and the subscription flood, production patterns and the C4 E07 connection; with anti-patterns, key terms, references",
    "02": "6 Mermaid diagrams — Pi-registry vs MCP-server (the externalization), three trust boundaries, server lifecycle, capability negotiation intersection, validation boundary (3 error classes), production failure modes; design-system colors",
    "03": "10 slides — reveal.js, dark theme, design-system teal; thesis, three primitives, trust boundaries, lifecycle, capability negotiation, validation boundary, three error classes, production operations, platform turn",
    "04": "Verbatim teaching transcript with [SLIDE N] cues, ~2,700 words across 10 slides",
    "05": "22 flashcards (TSV) — mix of recall, application, analysis; covers primitives, transports, lifecycle, capability negotiation, validation, error classes, failure modes, registry, production patterns",
    "06": "15 questions, 20/40/40 Bloom distribution (3 recall / 6 application / 6 analysis), 70% pass; validated JSON with rationale per question",
    "07": "Build a TypeScript MCP server — runnable lab with the official SDK: 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 (resource, prompt, subscription debouncing, idempotency key, HTTP+SSE transport)"
  }
}