D2 · Tool Design & MCP › Cluster 8 · MCP Security & Production

8.5 · Versioning, Observability & Ops

Run MCP in production

CONCEPT Pin the protocol version and the server version

MCP has two things that version independently, and production breaks when you ignore either. First, the protocol version — the spec is dated (e.g. 2025-06-18) and clients and servers negotiate a version during initialization. Pin and log the negotiated version; a server that only speaks an older revision may not support features (like the current authorization model) your host assumes. Second, the server's own capabilities — its tool set can change under you. A "rug pull" is when a previously-benign tool's description is swapped for a poisoned one after you approved it (8.1), so tool definitions and their versions should be tracked, not trusted-once.

🔑 The MCP protocol has a notifications/tools/list_changed signal — a server can tell the client its tool list changed. Treat a changed tool list as a re-review trigger, not a silent update: re-surface descriptions for approval rather than adopting new/altered tools blindly.

The same discipline appears in the Managed Agents surface: agents are versioned — every update creates a new immutable version, and a session can pin to a specific version for reproducibility and rollback. Pinning is how you get a known-good configuration you can roll back to when a change regresses.

CONCEPT Observability, rate limits, and monitoring

You can't secure what you can't see. Every tool call — the tool name, its full input, the result, latency, and whether a human approved it — should be logged and auditable. That log is what turns a suspected exfiltration (8.4) into a provable one, and it's the reason side-effecting tools get a dedicated, named hook rather than hiding in a generic bash call. The security guidance also stresses secure token storage (tokens cached or logged server-side are theft targets) and short-lived tokens with refresh rotation to bound the damage of a leak.

Ops concernWhat to doWhy
Protocol versionLog the negotiated version; pin expectationsFeature/auth support varies by revision
Server/tool versionTrack tool definitions; re-review on list_changedRug-pull & drift detection
Tool-call loggingRecord name, input, result, approver, latencyAudit trail for exfil / abuse
Rate limitsCap calls per tool / per session; back off on 429Contain runaway loops & abuse
Token hygieneShort-lived tokens, rotate refresh tokens, never log tokensLimit theft blast radius
Monitoring / alertingAlert on anomalies: new egress host, secret-path reads, error spikesDetect attacks in flight
Production checklist: allow-list servers (8.1) · OAuth 2.1 scoped tokens (8.2) · human gate on side effects (8.3) · isolate untrusted content (8.4) · version-pin + log + rate-limit + monitor (8.5). Security is the whole cluster, not one control.

DIAGRAM The observed, rate-limited tool-call path

flowchart TD M["Model requests tool call"] --> RL{"Under rate limit?"} RL -->|"no"| DROP["🔴 429 / back off
contain runaway loop"] RL -->|"yes"| VER{"Tool version /
list unchanged?"} VER -->|"changed"| REV["🟠 Re-review
(possible rug pull)"] VER -->|"known-good, pinned"| LOG["Log: name + input + approver"] LOG --> RUN["Invoke tool → log result + latency"] RUN --> MON["📊 Monitor: anomaly alerts
(new egress, secret reads)"] classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef gate fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; classDef bad fill:#f8d7da,stroke:#dc3545,color:#721c24; class LOG ok; class RUN ok; class MON ok; class REV gate; class DROP bad;

CODE Version-pinning + auditable tool-call logging

Pin the config to a known version, and emit a structured audit record for every call — including the approver, so an exfiltration attempt is traceable after the fact.

# Pin a session to a known-good, immutable agent version (rollback point).
session = client.beta.sessions.create(
    agent={"type": "agent", "id": agent.id, "version": agent.version},
    environment_id=env.id,
)

# Log every tool call: an audit trail is what makes exfil provable.
def audit(evt):
    log({
        "ts":          evt.timestamp,
        "mcp_version": negotiated_protocol_version,   # e.g. "2025-06-18"
        "server":      evt.server_name,
        "tool":        evt.name,
        "input":       evt.input,      # full args — exfil is visible here
        "approved_by": evt.approver,   # human or "auto"
        "result_len":  len(evt.result),
        "latency_ms":  evt.latency,
    })
    # NEVER log tokens or secret values — redact before writing.

TRADE-OFFS Pin & observe vs. auto-update & fire-and-forget

✅ Version-pin + log + monitor

  • Reproducible config; clean rollback on regression
  • Rug-pull & drift caught via list_changed re-review
  • Audit trail makes abuse provable
  • Rate limits contain runaway loops

⚠️ Auto-adopt latest, no logging

  • Always "current", less maintenance
  • But: a rug-pulled tool ships silently
  • No trail when an exfil is suspected
  • Unbounded calls = runaway cost & abuse

EXAM TRAPS

Trap: "There's one MCP version to worry about." → Two: the negotiated protocol version and the server's tool set/version. Both drift; log and pin both.
Trap: "A tool I approved once stays safe." → A rug pull swaps its description later. Treat tools/list_changed as a re-review trigger, not a silent update.
Trap: "Log everything, including the tokens, for completeness." → Never log tokens or secrets — cached/logged tokens are theft targets. Log tool name, input, and approver; redact secrets.
Trap: "Rate limits are a cost feature, not a security one." → They also contain runaway agent loops and abuse — a security control as much as a billing one.

PRACTICE

Q1 · Which two things version independently in an MCP deployment, and why track both?

The protocol version (negotiated at initialization, e.g. 2025-06-18 — determines which features/auth model are available) and the server's own tool set/version (which can change under you — a rug pull swaps a benign description for a poisoned one). Pin and log both; treat a tools/list_changed notification as a re-review trigger.

Q2 · What should a tool-call audit log capture, and what must it never contain?

Capture the tool name, its full input, the result (or its size), latency, the negotiated protocol/server version, and who approved it (human or auto). That's what turns a suspected exfiltration into a provable one. It must never contain tokens or secret values — those are theft targets; redact before writing.

Q3 · How does version pinning support safe operations?

Pinning a session (or client) to a specific, immutable agent/config version gives you a known-good, reproducible baseline and a rollback point: if a new version regresses or a tool definition is compromised, you pin new sessions back to the prior version while you investigate, instead of every session silently adopting the change.