> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ultra.security/llms.txt
> Use this file to discover all available pages before exploring further.

# How It Works

> Understand Ultra's proxy architecture

Ultra is a transparent proxy that sits between MCP clients and upstream MCP servers. Every request and response passes through Ultra's pipeline, where it's traced, logged, audited, and measured.

## The Proxy Model

```mermaid theme={null}
graph TD
    Client["<b>MCP Client</b>"]

    subgraph UltraBox[" "]
        direction TB
        UltraLabel["<b>Ultra</b>"]
        Transport["Transport"]
        Pipeline["Pipeline"]
        Aggregator["Aggregator"]
        UltraLabel ~~~ Transport
        Transport --> Pipeline
        Pipeline --> Aggregator
    end

    ServerA["Server"]
    ServerB["Server"]
    ServerC["Server"]

    Client -->|"MCP"| Transport
    Aggregator --> ServerA
    Aggregator --> ServerB
    Aggregator --> ServerC

    style UltraLabel fill:transparent,stroke:transparent
```

Your MCP client sees Ultra as a single MCP server. Ultra connects to multiple upstream servers and presents their combined tools, resources, and prompts as a unified interface.

## Key Components

### Transport Layer

Ultra supports all MCP transport types:

* **stdio** — Standard input/output (default for local clients like Claude Desktop and Codex)
* **HTTP/SSE** — Server-sent events over HTTP
* **Streamable HTTP** — Modern HTTP streaming transport

The client connects to Ultra over stdio, while Ultra connects to upstream servers using whatever transport they require (stdio for local commands, HTTP for remote servers).

### Pipeline

Every MCP request passes through a chain of **interceptors** before reaching the upstream server, and the response passes through the same chain in reverse order:

| Interceptor    | Purpose                                                   |
| -------------- | --------------------------------------------------------- |
| **Trace**      | Creates distributed traces for every request and response |
| **Logging**    | Structured request/response logging                       |
| **Audit**      | Records security audit events                             |
| **Metrics**    | Counters, histograms, latency tracking                    |
| **Governance** | Determines which tool calls are allowed                   |
| **Guardrails** | Evaluate each request and enforce policy                  |

Policy enforcement runs alongside observability, before the request reaches the upstream server. Enforcement is configured in [Ultra Hub](/hub/overview) and synced to every gateway. See [Guardrails](/hub/guardrails) and [Governance](/hub/governance).

### Aggregator

The aggregator manages connections to multiple upstream MCP servers and presents them as one:

* **Tool namespacing** — Tools from different servers are namespaced to avoid conflicts
* **Routing** — Calls are routed to the correct upstream based on the tool/resource name
* **Connection management** — Handles connection lifecycle across transports
* **OAuth** — Supports OAuth2 authentication for upstream servers that require it

### Storage

Observability data is stored locally on your gateway by default, with optional sync to Ultra Hub for cloud deployments.

### Hub Sync

When connected to Ultra Hub, your gateway periodically syncs traces and audit events to the cloud. The sync runs in the background with configurable intervals, and supports offline operation — data is stored locally and synced when connectivity is restored.

## What Gets Recorded

For every MCP operation, Ultra records:

* **Trace records** — Operation type, upstream server, tool/resource name, request/response payloads, duration, status, and OpenTelemetry trace/span IDs
* **Audit events** — Event type, severity, principal (client identity), outcome (allow/deny/error), and detailed context
* **Metrics** — Request counts, latency histograms, error rates, per-server breakdowns

## Next Steps

<CardGroup cols={2}>
  <Card title="Pipeline Deep Dive" icon="layer-group" href="/concepts/pipeline">
    Learn about the interceptor chain
  </Card>

  <Card title="Aggregator" icon="diagram-project" href="/concepts/aggregator">
    Understand multi-server routing
  </Card>
</CardGroup>