Skip to main content
Start Ultra as an MCP server that proxies requests to upstream MCP servers. Ultra acts as an intermediary between MCP clients and upstream servers, providing observability, audit logging, and metrics.

​
Usage

ultra start [flags]

​
Flags

FlagShortDefaultDescription
--config-cAuto-discoveredPath to configuration file

​
Examples

# Start with default config
ultra start

# Start with custom config
ultra start --config ~/.config/ultra/config.yaml

​
What Happens

  1. Loads configuration (auto-discovers or uses --config path)
  2. Initializes SQLite storage at ~/.config/ultra/ultra.db
  3. Sets up the observability pipeline (trace, logging, audit, metrics interceptors)
  4. Connects to all enabled upstream servers
  5. Registers aggregated tools, resources, and prompts
  6. Starts the MCP server on stdio transport
  7. If Hub is configured, starts background sync
Ultra communicates with the MCP client over stdio (stdin/stdout). All log output goes to stderr to avoid interfering with the MCP protocol.

​
Signals

  • Ctrl+C (SIGINT) or SIGTERM — Graceful shutdown. Ultra stops upstream connections, flushes pending data, and exits.
  • Client disconnect (EOF/pipe close) — Ultra exits gracefully when the MCP client disconnects.

​
Hub Sync

When Hub is enabled and the gateway is linked, ultra start runs background sync:
  • Data sync at the configured interval (default: 60s)
  • Heartbeats at half the sync interval (minimum 30s)
  • OAuth token refresh happens automatically
  • Terminal auth errors disable sync with a single warning (no error spam)