Skip to main content
Ultra is built as a layered proxy with clear separation between transport, processing, routing, and storage. It runs locally on each user’s machine as a single binary — MCP clients launch it as a subprocess, and all processing happens on-device. There are no cloud components in the data path.

​
System Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         MCP Clients                             │
│    (Claude Desktop, Cursor, VS Code, Claude Code, Codex, Goose)│
└─────────────────────────────┬───────────────────────────────────┘
                              │ MCP Protocol (stdio/HTTP)
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                            Ultra                                │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                   Transport Layer                         │  │
│  │            (stdio, HTTP/SSE, Streamable HTTP)             │  │
│  └───────────────────────────┬───────────────────────────────┘  │
│                              │                                  │
│  ┌───────────────────────────▼───────────────────────────────┐  │
│  │                  Pipeline (Interceptors)                   │  │
│  │                                                           │  │
│  │  ┌───────┐  ┌─────────┐  ┌───────┐  ┌─────────┐         │  │
│  │  │ Trace │→ │ Logging │→ │ Audit │→ │ Metrics │         │  │
│  │  │  (0)  │  │  (75)   │  │ (75)  │  │  (100)  │         │  │
│  │  └───────┘  └─────────┘  └───────┘  └─────────┘         │  │
│  └───────────────────────────┬───────────────────────────────┘  │
│                              │                                  │
│  ┌───────────────────────────▼───────────────────────────────┐  │
│  │                      Aggregator                           │  │
│  │          (Tool namespacing, routing, OAuth)                │  │
│  └──┬──────────────┬──────────────┬──────────────┬───────────┘  │
│     │              │              │              │              │
└─────┼──────────────┼──────────────┼──────────────┼──────────────┘
      │              │              │              │
      ▼              ▼              ▼              ▼
┌───────────┐  ┌───────────┐  ┌───────────┐  ┌───────────┐
│ Upstream  │  │ Upstream  │  │ Upstream  │  │ Upstream  │
│ Server 1  │  │ Server 2  │  │ Server 3  │  │ Server N  │
│ (stdio)   │  │ (HTTP)    │  │ (SSE)     │  │  ...      │
└───────────┘  └───────────┘  └───────────┘  └───────────┘

                Storage Layer
┌─────────────────────────────────────────────┐
│  ┌─────────┐  ┌─────────┐  ┌─────────────┐ │
│  │ Memory  │  │ SQLite  │  │ PostgreSQL  │ │
│  │ (test)  │  │ (local) │  │  (cloud)    │ │
│  └─────────┘  └─────────┘  └─────────────┘ │
└─────────────────────────────────────────────┘

​
Layers

​
Transport Layer

Handles MCP protocol communication. Ultra supports all MCP transport types:
  • stdio — Standard I/O for local clients (Claude Desktop, Cursor, Codex)
  • HTTP/SSE — Server-sent events over HTTP
  • Streamable HTTP — Modern HTTP streaming
The client-facing side typically uses stdio (since MCP clients launch Ultra as a subprocess), while upstream connections use whatever transport the server requires.

​
Pipeline

The interceptor chain processes every request and response. Interceptors run in priority order for requests and reverse order for responses.

​
Aggregator

The aggregator manages connections to upstream MCP servers and presents them as a single unified interface to the client.

​
Storage

Pluggable storage backends for observability data:
BackendUse CasePersistence
MemoryTesting, developmentNone (lost on restart)
SQLiteLocal deployments~/.config/ultra/ultra.db
PostgreSQLCloud/Hub deploymentsPersistent
All backends implement the same Storage interface, supporting traces, audit events, metrics, and aggregate statistics.

​
Key Dependencies

DependencyPurpose
modelcontextprotocol/go-sdkOfficial MCP SDK (transport, protocol)
spf13/cobraCLI framework
charmbracelet/bubbleteaInteractive terminal UI
charmbracelet/lipglossTerminal styling
go.opentelemetry.io/otelDistributed tracing and metrics
labstack/echo/v4Web framework (dashboard, Hub)
jackc/pgx/v5PostgreSQL driver