# DD-22 — Diagrams: MCP Building Production Tool Servers

Six Mermaid diagrams. Color coding per the design system:

- `#14141f` — panel fill (structural element)
- `#08080c` — nested node background (the detail inside)
- `#5eead4` — teal accent (semantic / principle / the load-bearing idea)
- `#f0a868` — warn (a structural gap or caveat the reader must notice)
- `#f08080` — danger (an impact, a failure mode, a thing that breaks production)

---

## Diagram 1 — The Externalization: Pi's Registry vs. an MCP Server

**Type**: Side-by-side flowchart (LR)

**Purpose**: The thesis in one picture. Pi's four tools are function references compiled into the harness. An MCP server is a separate process, discovered at runtime, versioned independently. The structural difference between a personal harness and a platform.

**Reading the diagram**: Left = Pi (DD-01), monolithic, source-coupled. Right = MCP, external, runtime-discovered. The teal arrow is the wire protocol that replaces the function call.

```mermaid
flowchart LR
    subgraph Pi["Pi (DD-01) — Personal Harness"]
        direction TB
        PiLoop["agent loop"]
        PiReg["tool-registry.ts<br/>read_file · write_file<br/>edit_file · bash"]
        PiLoop -->|"function call"| PiReg
    end

    subgraph MCP["Platform — MCP"]
        direction TB
        Agent["agent loop"]
        Client["MCP client"]
        Proto["JSON-RPC over stdio / HTTP+SSE"]
        Server1["ticket-server v1.2"]
        Server2["crm-server v2.0"]
        Server3["db-server v0.9"]
        Agent --> Client
        Client -->|"tools/list · tools/call"| Proto
        Proto --> Server1
        Proto --> Server2
        Proto --> Server3
    end

    Pi -.->|"rebuild to add a tool"| PiReg
    Client -.->|"discover at runtime"| Server1

    classDef panel fill:#14141f,stroke:#5eead4,stroke-width:1px,color:#e4e4e8
    classDef nested fill:#08080c,stroke:#3a3a48,stroke-width:1px,color:#9494a0
    classDef principle fill:#08080c,stroke:#5eead4,stroke-width:2px,color:#5eead4
    classDef gap fill:#08080c,stroke:#f0a868,stroke-width:1px,color:#f0a868

    class Pi,MCP panel
    class PiLoop,PiReg,Agent,Client,Server1,Server2,Server3 nested
    class Proto principle
```

---

## Diagram 2 — The Three Primitives and Their Trust Boundaries

**Type**: Flowchart (TB) with three parallel lanes

**Purpose**: Tools, resources, and prompts look similar but map to different trust boundaries. The model initiates tool calls (untrusted input, must be validated). The user/client initiates resource reads (semi-trusted, server vouches for data). The user initiates prompts (trusted template, server authored).

**Reading the diagram**: Three lanes top-to-bottom. Each primitive has an initiator, a validation requirement, and a security posture. The teal border marks the validation boundary; the warn border marks where untrusted input enters.

```mermaid
flowchart TB
    subgraph ToolLane["TOOL — model-invoked function"]
        direction TB
        T1["Model decides to call"]
        T2["Model produces arguments<br/>against JSON Schema"]
        T3["Server validates<br/>against schema"]
        T4["Server executes"]
        T1 --> T2 --> T3 --> T4
    end

    subgraph ResourceLane["RESOURCE — server-exposed data"]
        direction TB
        R1["User / client decides<br/>to read"]
        R2["Client sends<br/>resources/read"]
        R3["Server returns content<br/>by URI"]
        R1 --> R2 --> R3
    end

    subgraph PromptLane["PROMPT — server-authored template"]
        direction TB
        P1["User selects prompt<br/>from menu"]
        P2["Client fills parameters"]
        P3["Server renders<br/>the template"]
        P1 --> P2 --> P3
    end

    T2 -.->|"untrusted input"| T3
    R3 -.->|"server vouches"| R1
    P3 -.->|"server authored"| P1

    classDef lane fill:#14141f,stroke:#3a3a48,stroke-width:1px,color:#e4e4e8
    classDef node fill:#08080c,stroke:#3a3a48,stroke-width:1px,color:#e4e4e8
    classDef boundary fill:#08080c,stroke:#5eead4,stroke-width:2px,color:#5eead4
    classDef untrusted fill:#08080c,stroke:#f0a868,stroke-width:1px,color:#f0a868
    classDef trusted fill:#08080c,stroke:#5eead4,stroke-width:1px,color:#9494a0

    class ToolLane,ResourceLane,PromptLane lane
    class T1,T4,R2,P2 node
    class T3 boundary
    class T2,R3 untrusted
    class R1,P1,P3 trusted
```

---

## Diagram 3 — The Server Lifecycle

**Type**: Flowchart (TB) with sequential phases

**Purpose**: The full lifecycle a production server goes through. Initialization → capability negotiation → the message loop → graceful shutdown. Each phase has a specific protocol purpose. Skipping initialization (sending `tools/call` before `initialized`) is the most common integration bug.

**Reading the diagram**: Top-to-bottom sequence. The teal nodes are protocol-required; the warn node is the signal that triggers shutdown; the rest are loop operations. The shutdown path must clean up before exit.

```mermaid
flowchart TB
    Start([Client spawns / connects]) --> Init["initialize<br/>client sends protocol version<br/>+ client capabilities"]
    Init --> InitResp["server responds<br/>protocol version<br/>+ server capabilities<br/>+ server identity"]
    InitResp --> Ready["notifications/initialized<br/>handshake complete"]
    Ready --> Loop{Message Loop}

    Loop -->|"tools/list"| ListTools["server returns catalog"]
    Loop -->|"tools/call"| CallTool["validate + execute + respond"]
    Loop -->|"resources/read"| ReadRes["return content by URI"]
    Loop -->|"notifications/.../updated"| Push["server pushes update"]
    Loop -->|"SIGTERM / disconnect"| Shutdown

    ListTools --> Loop
    CallTool --> Loop
    ReadRes --> Loop
    Push --> Loop

    Shutdown["SHUTDOWN<br/>finish in-flight requests<br/>close handles<br/>flush logs"]
    Shutdown --> Exit([exit 0])

    classDef phase fill:#08080c,stroke:#5eead4,stroke-width:1px,color:#5eead4
    classDef loop fill:#08080c,stroke:#3a3a48,stroke-width:1px,color:#e4e4e8
    classDef danger fill:#08080c,stroke:#f08080,stroke-width:1px,color:#f08080
    classDef terminal fill:#14141f,stroke:#5a5a68,stroke-width:1px,color:#9494a0

    class Init,InitResp,Ready phase
    class Loop,ListTools,CallTool,ReadRes,Push loop
    class Shutdown danger
    class Start,Exit terminal
```

---

## Diagram 4 — Capability Negotiation: The Contract in Force

**Type**: Flowchart (LR) with a decision matrix

**Purpose**: Capabilities are not booleans — they are structured objects. The rule is "only use what both sides advertised." This diagram shows how a client written against a new server degrades gracefully, and how a client written against an old server survives a server upgrade.

**Reading the diagram**: Client offers capabilities (top); server offers capabilities (bottom). The intersection (teal) is what the session may use. Anything outside the intersection is forbidden for this session.

```mermaid
flowchart LR
    subgraph ClientCaps["Client advertises"]
        CC1["tools (listChanged: true)"]
        CC2["resources (subscribe: true)"]
        CC3["roots (listChanged: true)"]
        CC4["prompts"]
    end

    subgraph ServerCaps["Server advertises"]
        SC1["tools (listChanged: false)"]
        SC2["resources (subscribe: true)"]
        SC3["logging"]
    end

    subgraph Negotiated["Session may use — the intersection"]
        N1["tools/list · tools/call"]
        N2["resources/read · resources/subscribe"]
        N3["prompts/list · prompts/get"]
    end

    CC1 -.->|"intersect"| N1
    SC1 -.->|"intersect"| N1
    CC2 -.->|"intersect"| N2
    SC2 -.->|"intersect"| N2
    CC4 -.->|"client only"| N3

    CC3 -.-|"no server support —<br/>client must not query roots"| X1["FORBIDDEN"]
    SC3 -.-|"no client support —<br/>server must not send logs"| X2["FORBIDDEN"]

    classDef cap fill:#08080c,stroke:#3a3a48,stroke-width:1px,color:#e4e4e8
    classDef ok fill:#08080c,stroke:#5eead4,stroke-width:2px,color:#5eead4
    classDef forbidden fill:#08080c,stroke:#f08080,stroke-width:1px,color:#f08080
    classDef panel fill:#14141f,stroke:#5a5a68,stroke-width:1px,color:#e4e4e8

    class CC1,CC2,CC3,CC4,SC1,SC2,SC3 cap
    class N1,N2,N3 ok
    class X1,X2 forbidden
    class ClientCaps,ServerCaps,Negotiated panel
```

---

## Diagram 5 — The Validation Boundary

**Type**: Flowchart (TB) showing the three-class error model

**Purpose**: A tool call can fail in three distinct ways, each with a different recovery path. The model needs to know *which* failure it got. This diagram traces the validation-and-execution path and marks the three failure classes.

**Reading the diagram**: The request enters at top. Validation gates execution. The teal nodes are success paths. The three failure classes (warn/danger) each return a different `isError` payload that the model reads and responds to differently.

```mermaid
flowchart TB
    Call(["tools/call arrives<br/>name + arguments"]) --> Lookup{"tool exists<br/>in catalog?"}

    Lookup -->|"no"| Err1["CLASS 1: Unknown tool<br/>isError: true<br/>text: Unknown tool: 'X'<br/>model can: stop calling it"]
    Lookup -->|"yes"| Validate{"arguments<br/>conform to schema?"}

    Validate -->|"no"| Err2["CLASS 2: Validation failure<br/>isError: true<br/>text: Invalid arguments: ...<br/>model can: retry with fixed args"]
    Validate -->|"yes"| Exec["dispatch to handler<br/>execute business logic"]

    Exec --> Outcome{"threw?"}
    Outcome -->|"no"| Success(["return result<br/>content: text/json<br/>model reads result"])
    Outcome -->|"yes"| Err3["CLASS 3: Execution failure<br/>isError: true<br/>text: Tool execution failed: ...<br/>model can: retry or report"]

    classDef start fill:#14141f,stroke:#5a5a68,stroke-width:1px,color:#9494a0
    classDef decision fill:#08080c,stroke:#5eead4,stroke-width:1px,color:#5eead4
    classDef success fill:#08080c,stroke:#5eead4,stroke-width:2px,color:#5eead4
    classDef class1 fill:#08080c,stroke:#f0a868,stroke-width:1px,color:#f0a868
    classDef class2 fill:#08080c,stroke:#f0a868,stroke-width:1px,color:#f0a868
    classDef class3 fill:#08080c,stroke:#f08080,stroke-width:1px,color:#f08080

    class Call start
    class Lookup,Validate,Outcome decision
    class Exec,Success success
    class Err1 class1
    class Err2 class2
    class Err3 class3
```

---

## Diagram 6 — Production Failure Modes

**Type**: Flowchart (TB) with four failure scenarios

**Purpose**: The four ways a production MCP deployment breaks. Each has a signature and a mitigation. This is the operator's diagnostic map.

**Reading the diagram**: Four failure scenarios, each with a cause, a symptom, and a mitigation. The teal border is the mitigation; the danger border is the impact if unmitigated.

```mermaid
flowchart TB
    subgraph FM1["Failure 1: stdout corruption"]
        direction TB
        F1C["cause: console.log on stdio transport"]
        F1S["symptom: client gets JSON parse error,<br/>disconnects, reconnects in a loop"]
        F1M["fix: log to stderr only"]
        F1C --> F1S --> F1M
    end

    subgraph FM2["Failure 2: schema drift"]
        direction TB
        F2C["cause: server upgraded,<br/>tool input schema changed"]
        F2S["symptom: model produces args<br/>for old schema, validation fails"]
        F2M["fix: namespace + version tools,<br/>pin server version in registry"]
        F2C --> F2S --> F2M
    end

    subgraph FM3["Failure 3: subscription flood"]
        direction TB
        F3C["cause: subscribed to volatile resource<br/>(live log, event stream)"]
        F3S["symptom: context fills with update noise,<br/>model loses the conversation"]
        F3M["fix: debounce on server,<br/>unsubscribe aggressively"]
        F3C --> F3S --> F3M
    end

    subgraph FM4["Failure 4: no graceful shutdown"]
        direction TB
        F4C["cause: SIGTERM unhandled,<br/>orchestrator force-kills after timeout"]
        F4S["symptom: in-flight requests orphaned,<br/>temp files leak, transactions open"]
        F4M["fix: handle SIGTERM from day one,<br/>drain before exit"]
        F4C --> F4S --> F4M
    end

    classDef scenario fill:#14141f,stroke:#3a3a48,stroke-width:1px,color:#e4e4e8
    classDef cause fill:#08080c,stroke:#f08080,stroke-width:1px,color:#f08080
    classDef symptom fill:#08080c,stroke:#f0a868,stroke-width:1px,color:#f0a868
    classDef fix fill:#08080c,stroke:#5eead4,stroke-width:2px,color:#5eead4

    class FM1,FM2,FM3,FM4 scenario
    class F1C,F2C,F3C,F4C cause
    class F1S,F2S,F3S,F4S symptom
    class F1M,F2M,F3M,F4M fix
```

---

## Validation Notes

- All diagrams use `flowchart` with `TB` or `LR` direction — no `sequenceDiagram` or `classDiagram` (kept to one type for consistency).
- Subgraph syntax validated: every `subgraph` has a matching `end`.
- Color coding is consistent: teal (`#5eead4`) for principle/success/fix; warn (`#f0a868`) for gap/symptom/untrusted; danger (`#f08080`) for impact/cause/failure.
- No diagram exceeds 12 nodes — readable at slide scale.
- Diagram 1 establishes the thesis; Diagrams 2-5 decompose the protocol; Diagram 6 maps production operations.