Skip to main content
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

MCP Client (Claude Desktop, Cursor, etc.)
    │
    │  MCP Protocol (stdio)
    ▼
┌─────────────────────────────┐
│           Ultra             │
│                             │
│  ┌───────────────────────┐  │
│  │   Transport Layer     │  │
│  │  (stdio, HTTP, SSE)   │  │
│  └───────────┬───────────┘  │
│              │              │
│  ┌───────────▼───────────┐  │
│  │      Pipeline         │  │
│  │  Trace → Log → Audit  │  │
│  │      → Metrics        │  │
│  └───────────┬───────────┘  │
│              │              │
│  ┌───────────▼───────────┐  │
│  │     Aggregator        │  │
│  │  (routing, namespacing│  │
│  │   multi-server)       │  │
│  └──┬──────┬──────┬──────┘  │
│     │      │      │         │
└─────┼──────┼──────┼─────────┘
      │      │      │
      ▼      ▼      ▼
   Server  Server  Server
    (A)     (B)     (C)
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)
  • 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:
InterceptorPriorityPurposeFailure Mode
Trace0 (first)Creates OpenTelemetry spans, stores trace recordsFail open
Logging75Structured request/response loggingFail open
Audit75Records security audit eventsFail closed on response
Metrics100 (last)Counters, histograms, latency trackingFail open
Fail open means the interceptor absorbs errors — a logging failure won’t block your MCP request. Fail closed means errors are propagated — the audit interceptor blocks responses if it can’t record the audit event, ensuring complete audit trails for compliance. Any error in the BeforeRequest phase blocks the request entirely (fail closed by default).
Auth and Policy interceptors are planned but not yet implemented. See Roadmap: Policy Engine.

​
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 (e.g., upstream__toolname)
  • Routing — Calls are routed to the correct upstream based on the tool/resource name
  • Connection management — Handles stdio process lifecycle and HTTP connections
  • OAuth — Supports OAuth2 authentication for upstream servers that require it

​
Storage

Ultra stores all observability data locally:
  • Default: SQLite at ~/.config/ultra/ultra.db
  • Cloud: PostgreSQL for Ultra Hub deployments
  • Test: In-memory storage for development

​
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

Pipeline Deep Dive

Learn about the interceptor chain

Aggregator

Understand multi-server routing