# ToolHost — Architecture One-Pager

*Anchor: project-docs/02-architecture (system design), 00-FINAL-GOAL.md §5 #3/#6/#10/#12*

## What ToolHost is

A governed access layer for MCP: one endpoint, one identity, every tool call authenticated,
authorized, metered, audited, and schema-verified before it reaches a backend.

## The per-call governance pipeline

Every call — list or invoke, from any client — passes through the same ordered pipeline before
it can reach a backend:

```
auth → view → schema-pin → policy → rate-limit → breaker → credentials → trace → backend → redact → audit
```

The aggregator routes calls; it never decides whether a call is allowed — policy and rate-limit
run before forwarding, on both list and call paths, unconditionally.

## Three planes

- **Data plane** — the MCP front door and the aggregation/routing engine that talks to backends.
- **Control plane** — configuration, policy, and runtime generations. [Anchor: 00-FINAL-GOAL.md §5
  #6] Zero-dropped-request reload: every config change — including every policy edit — is
  plan → apply → new Generation; in-flight calls complete on their entry Generation; what was
  previewed is provably what ran (plan hash in evidence). Policy edits are Generation-bound, not
  instantaneous — instant control is the toggle bucket's job.
- **Identity plane** — simultaneously an OAuth resource server, an authorization-server facade,
  and an OAuth client. [Anchor: 00-FINAL-GOAL.md §5 #3] No token passthrough, structurally: the
  downstream credential cannot reach an upstream request because no API exists through which it
  could.

## Kill switch

[Anchor: 00-FINAL-GOAL.md §5 #1] Disable a tool or backend and it is dead on the issuing replica
**immediately**, cluster-wide **≤2s via NOTIFY in the healthy case, ≤30s guaranteed** via the poll
backstop; per-replica epoch lag is visible in ready-detail — a lagging replica can never be
silent. (Never state an unconditional ≤2s.)

## Rate/quota honesty

[Anchor: 00-FINAL-GOAL.md §5 #5] Hard caps enforced within a **+5%-per-replica local-allowance
tolerance (worst case N×5% overshoot)**; `allowance: 0` buys exact per-call accounting at a
latency cost; `strict` limits fail closed on store outage, non-strict fail open **with alarm** —
a documented choice, not an accident. (The bare words "hard caps, fail closed" without this
qualification are not a permitted claim.)

## Fail-closed, no exceptions

[Anchor: 00-FINAL-GOAL.md §5 #10] Every ambiguity in the system — missing claim, unknown kid,
unpinned schema, absent policy, oversized args under an args-condition, malformed deny rule, cold
resolver with the store down — resolves to a well-formed deny.

## Governance is era-blind

[Anchor: 00-FINAL-GOAL.md §5 #12] Every guarantee above holds byte-identically under both MCP
eras (session-based and the emerging stateless transport); the dual-era conformance suite is the
regression net.

## Deployment posture

Single binary, one config schema across every profile — local dev, Docker Compose, or
Kubernetes. Today's honestly-claimed posture is **single-replica + fast restart**, not high
availability; see `07-deployment-profiles.md` for the exact claim and its gate.

---
*This is a synthesis document. Every specific guarantee cited above is stated in its reconciled
§5 form and traces to the anchors noted inline. No latency, scale, or availability number is
asserted beyond what those anchors license.*