Architecture

fold presents many teams’ MCP servers — any language, any SDK era — as one governed virtual server. fold is the one; fold.run is the execution.

Request pipeline

POST /mcp
 → host validation      DNS-rebinding protection (Host/Origin allowlist)
 → observability        span start, trace context extracted (SEP-414)
 → authenticate         Bearer → issuer allowlist → JWKS → audience → Principal
 → authorize            body-free policy over Mcp-Method/Mcp-Name headers (SEP-2243)
 → rate limit           global window → 429 + Retry-After
 → route                federated fan-out (lists/discover/ping) or named routing
 → onRouted             authoritative policy check (body-derived names included)
 → per-upstream guards  rate limit, circuit breaker
 → translate            era mismatch only: envelope upgrade or legacy bridge
 → proxy                credentials attached, trace injected, response streamed
 → egress               per-principal list filtering, namespace rewriting
 → observe              span end, metrics, audit event (single exit door)

Responses stream through untouched on the fast path; bodies are only parsed where the gateway must rewrite (namespacing, list merging, translation) or filter (policy).

Era translation

Client ↔ Upstream	Mechanism
modern ↔ modern	Stateless passthrough; Mcp-Name header routing without body parse.
legacy ↔ modern	North termination: fold answers initialize, owns the session, upgrades each request to the self-describing 2026-07-28 envelope (SEP-2575/2567).
modern ↔ legacy	South bridge: one held SDK-client session per protocol: "legacy" upstream; results modernized (resultType, cache fields); fold answers era probes.
legacy ↔ legacy	Single upstream: pure passthrough (matched eras never translate). Federated: north termination + south bridge compose.

Package layout

Portable packages (contracts, core, protocol, config, auth, policy, audit, observability, bridge) build on web-standard APIs plus an allowlist (hono, zod, jose, @opentelemetry/api, MCP SDK client/core) — enforced by tools/check-boundaries.mjs. Only runtime-node and runtime-workers touch node:* / cloudflare:*, implementing the RuntimePlatform ports: KV, counters, sessions, secrets, waitUntil, upstream fetch.

Subsystems integrate through GatewayHooks (authenticate/authorize/routed/upstream-request/upstream-response/response/error) composed with composeHooks — core never imports auth, policy, audit, or observability.

Spec alignment

spec-alignment.json is the source of truth: spec version, SDK pins (mirrored by the pnpm mcp catalog), extension status, and per-SEP coverage. SPEC_ALIGNMENT.md is generated from it and drift-gated in CI. A daily watcher diffs npm/PyPI/the spec repo’s seps/ directory and opens a human-reviewed PR on any movement. The official conformance suite runs in CI through fold on both runtimes — a gateway that stops being invisible fails the build.