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, automatically detecting the correct transport type (SSE vs. Streamable HTTP)
  • Manages connection health
  • Handles authentication (including OAuth2 flows)

​
Server Probing and MCP Normalization

MCP servers are notoriously inconsistent. Some require --stdio flags, others need subcommands like server or serve, and many output help text instead of speaking the MCP protocol by default. Ultra handles all of this automatically so you don’t need a separate debugger tool.

​
Stdio Server Probing

When Ultra connects to a stdio server, it performs an MCP protocol handshake to verify the server responds with valid JSON-RPC. If the handshake fails because the server outputs non-JSON (help text, usage info, or error messages), Ultra automatically tries common argument patterns concurrently:
  • --stdio
  • server
  • serve
  • server --stdio
  • server --mcp-only
  • start --stdio
  • --mcp
If any combination works, Ultra uses it automatically and stores the corrected args in your config. You never need to figure out the right invocation yourself. This probing happens during ultra add so servers are validated before they’re added to your configuration.

​
HTTP Server Probing

For HTTP-based servers, Ultra probes the connection and detects authentication requirements:
Server ResponseWhat Ultra Does
200 / 204Connects directly, no auth needed
401Checks for OAuth support (RFC 8414) and initiates the appropriate auth flow
403Prompts for a bearer token or API key
Ultra also auto-detects the correct HTTP transport type from the server URL, choosing SSE or Streamable HTTP automatically.

​
Auto-Reconnection

Connections drop. Servers restart. Networks hiccup. Ultra detects stale connections (EOF, broken pipe, connection reset) and transparently reconnects without interrupting your workflow. Each upstream server reconnects independently, so one flaky server doesn’t block the others.

​
Actionable Error Messages

When a server can’t be connected or auto-fixed, Ultra provides context-specific guidance rather than a generic error:
  • Auth errors: Tells you whether the server needs OAuth or a token, with setup instructions
  • Protocol errors: Suggests the server may need a specific flag, with a link to your config file
  • Network errors: Distinguishes between “server unreachable” and “server timed out” with appropriate next steps

​
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