Conduit architecture

Conduit implements a narrow federation path:

flowchart LR
    C[MCP client] --> I[Ingress]
    I --> R[Immutable registry + policy]
    R --> A[Durable authorization audit]
    A --> D[Dispatcher]
    D --> M[Downstream Streamable HTTP MCP]

Ingress accepts MCP 2026-07-28 on the local Streamable HTTP endpoint. It serves server/discover, the published aggregate for tools/list, and hands tools/call to the dispatcher. It does not forward the client request as a general proxy request.

Discovery and aggregate publication

Each refresh uses a configured downstream’s Streamable HTTP endpoint for server/discover and tools/list. Catalogs are bounded by the configured page, tool, and byte limits. A successful catalog is published into an immutable aggregate generation. A failed refresh removes that downstream’s previous catalog; a later successful refresh recovers it.

Aggregate tool names are deterministic: <downstream-id>.<downstream-tool-name>. Each published name has an exact Route containing the configured downstream identity and original tool name. Calls therefore use the stored mapping; names are never split to infer a route. Publication is deterministic, policy-filtered, and rejects collisions or aggregate limits instead of exposing a partial aggregate.

Policy and authorization

Policy allow/deny rules filter public tools/list output. For a call, the registry prepares the route, then authorization is committed while verifying that the same aggregate generation and policy still apply. The durable authorization audit record is written inside that linearization boundary. If it cannot be written, no downstream transport starts.

The registry lock is released before network I/O. This makes refresh publication independent of downstream execution while preventing a stale prepared route from being authorized.

Dispatch and outcomes

The dispatcher is the only production owner of downstream tools/call. It sends one request to the exact configured endpoint, with the original downstream tool name and downstream-owned configured headers. It does not perform discovery, initialization, redirects, or automatic retries for a call.

Terminal JSON results and correlated JSON-RPC errors are relayed with the original client request ID. Response bodies are bounded before parsing. If transport has started and the final state is not safely known—for example a timeout, malformed or oversized response, or unsupported SSE/progress response—the result is recorded and returned as uncertain-after-dispatch. Conduit does not retry such a call.

When a downstream response creates a Streamable HTTP session, Conduit records only that invocation’s returned session ID and performs at most one bounded cleanup DELETE against the same endpoint. Cleanup uses the invocation/shutdown context and cannot replace a valid tool result. Stateless calls have no cleanup request.

Lifecycle and readiness

The health state records liveness, audit availability, downstream refresh state, and the currently published aggregate generation. Conduit is ready only after every configured downstream has attempted initial refresh, at least one is healthy, the aggregate is usable, and audit storage is available.

On shutdown, Conduit stops dispatch admission and HTTP acceptance, cancels active dispatch contexts, waits for their terminal audit paths, and only then closes audit storage. Refresh processing is cancelled and joined as part of the same shutdown sequence.