Skip to main content
The aggregator is Ultra’s central orchestrator. It manages connections to multiple upstream MCP servers and presents their combined tools, resources, and prompts as a single unified interface to the MCP client.

​
How It Works

Your MCP client sees Ultra as one server. Behind the scenes, Ultra connects to multiple upstream servers and merges their capabilities: 
Client sees:                    Actually routed to:
┌─────────────────────┐
│ filesystem__ls      │ ──────→ Filesystem Server
│ filesystem__read    │ ──────→ Filesystem Server
│ github__search      │ ──────→ GitHub Server
│ github__create_pr   │ ──────→ GitHub Server
│ notion__query       │ ──────→ Notion Server
│ ultra_status        │ ──────→ Ultra (built-in)
└─────────────────────┘

​
Tool Namespacing

To avoid name conflicts when multiple servers provide similarly-named tools, the aggregator prefixes tool names with the upstream server name: 
{upstream_name}__{tool_name}
For example, if you have a filesystem server with a read tool and a github server with a read tool, they become:
  • filesystem__read
  • github__read
This ensures every tool has a unique name that the client (and AI agent) can unambiguously reference.

​
Routing

When a tool call comes in, the aggregator:
  1. Parses the namespaced tool name to identify the upstream server
  2. Routes the request through the pipeline for observability
  3. Forwards the call to the correct upstream server
  4. Returns the response back through the pipeline to the client
The same routing applies to resources and prompts.

​
Connection Management

The aggregator handles the lifecycle of upstream connections:

​
Stdio Servers

For command-based servers, the aggregator:
  • Spawns the process with configured command, args, and env vars
  • Communicates over stdin/stdout
  • Handles process lifecycle (start, restart, cleanup)

​
HTTP Servers

For URL-based servers, the aggregator:
  • Establishes HTTP/SSE connections
  • Manages connection health
  • Handles authentication (including OAuth2 flows)

​
OAuth2 Support

The aggregator supports OAuth2 authentication for upstream servers that require it. When a server responds with a 401, Ultra can:
  • Initiate an OAuth2 PKCE flow
  • Open a browser for user authorization
  • Store and refresh tokens automatically

​
Built-in Tools

Ultra registers one built-in tool:
ToolDescription
ultra_statusReturns Ultra’s health status, version, upstream count, and aggregated tool count
This tool is always available regardless of upstream configuration.

​
Startup Flow

When ultra start runs:
  1. Load configuration and validate upstream entries
  2. Initialize storage and observability
  3. Create the pipeline with interceptors
  4. Start the aggregator — connect to all enabled upstream servers
  5. Discover capabilities — list tools, resources, and prompts from each upstream
  6. Register aggregated capabilities — namespaced tools/resources/prompts on the MCP server
  7. Start the MCP server on stdio transport
  8. (Optional) Start Hub background sync