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

​
How It Works

Your agent sees Ultra as one server. Behind the scenes, Ultra connects to multiple upstream connectors and merges their capabilities:

​
Tool Namespacing

To avoid name conflicts when multiple connectors provide similarly-named tools, the aggregator prefixes tool names with the upstream connector name:
For example, if you have a filesystem connector with a read tool and a github connector with a read tool, they become:
  • filesystem__read
  • github__read
This ensures every tool has a unique name that the agent can unambiguously reference.

​
Routing

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

​
Connection Management

The aggregator handles the lifecycle of upstream connections:

​
Stdio Connectors

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

​
HTTP Connectors

For URL-based connectors, the aggregator:
  • Establishes HTTP/SSE connections, automatically detecting the correct transport type (SSE vs. Streamable HTTP)
  • Manages connection health
  • Handles authentication (including OAuth2 flows)

​
Connector Probing and MCP Normalization

MCP connectors 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 Connector Probing

When Ultra connects to a stdio connector, it performs an MCP protocol handshake to verify the connector responds with valid JSON-RPC. If the handshake fails because the connector 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 connectors are validated before they’re added to your configuration.

​
HTTP Connector Probing

For HTTP-based connectors, Ultra probes the connection and detects authentication requirements: Ultra also auto-detects the correct HTTP transport type from the connector URL, choosing SSE or Streamable HTTP automatically.

​
Auto-Reconnection

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

​
Actionable Error Messages

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

​
OAuth2 Support

The aggregator supports OAuth2 authentication for upstream connectors that require it. When a connector 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: 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 connectors
  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