ultra install

Install Ultra into MCP clients

Detect installed MCP clients and configure them to use Ultra as their MCP server.

Usage

ultra install [flags]

Flags

Flag	Short	Default	Description
--client	-c		Target client (claude, cursor, vscode, cline, claude_code, windsurf, goose, codex, opencode, gemini, roocode, amazonq, lmstudio, ona, hermes)
--all		false	Install into all detected MCP clients (non-interactive)
--config			Path to Ultra config file
--no-backup		false	Skip backup of existing client config
--yes	-y	false	Skip confirmation prompt
--list	-l	false	List detected clients without installing

Examples

# Interactive installation wizard
ultra install

# Install into Claude Desktop only
ultra install --client claude

# Install into Cursor only
ultra install --client cursor

# Install into Codex only
ultra install --client codex

# Install into Ona
ultra install --client ona

# Install into Hermes
ultra install --client hermes

# List detected clients without installing
ultra install --list

# Install into all detected clients (non-interactive, used by MDM)
ultra install --all

Supported Clients

Client	Flag Value	Aliases
Claude Desktop	claude	claude-desktop, claude_desktop
Cursor	cursor
Codex	codex	codex-cli
VS Code	vscode
Claude Code	claude_code	claude-code
Windsurf	windsurf
Goose	goose
OpenCode	opencode
Gemini	gemini
Roo Code	roocode	roo-code, roo_code
Amazon Q	amazonq	amazon-q, amazon_q
LM Studio	lmstudio	lm-studio, lm_studio
Ona	ona
Hermes	hermes

What It Does

The install command writes Ultra as an MCP server entry in the client’s configuration. For example, Claude Desktop’s config becomes:

{
  "mcpServers": {
    "ultra": {
      "command": "/usr/local/bin/ultra",
      "args": ["start"]
    }
  }
}

For Codex, the TOML config at ~/.codex/config.toml becomes:

[mcp_servers.ultra]
command = "/usr/local/bin/ultra"
args = ["start"]

For Hermes, the YAML config at ~/.hermes/config.yaml becomes:

mcp_servers:
  ultra:
    command: /usr/local/bin/ultra
    args:
      - start
    enabled: true

Existing servers and any non-MCP top-level keys in the Hermes config are preserved. Servers with enabled: false are filtered out when discovering existing entries.

If --config is specified, the args include --config <path>.

Auto-linking with deploy keys

Ultra auto-links the gateway to Hub at install time when invoked via:

• ultra install --all — used by MDM deployments to configure every detected client in one shot
• ultra install --client ona — used by the Ona devcontainer entry point, which needs the gateway named before any MCP client starts

After configuring clients, these paths check for a deploy key (via ULTRA_DEPLOY_KEY environment variable, config file, or managed preferences). If a deploy key is found, the gateway is linked immediately:

• The gateway registers with the workspace scoped by the deploy key
• Device identity (email, external ID) is resolved from available sources (MDM preferences, environment variables)
• The gateway appears in the Hub dashboard before any MCP client launches

For all other install paths — the interactive wizard, plain ultra install --yes, and per-client installs other than Ona — the gateway links during the first ultra start instead. OAuth-authenticated users always link at ultra start, regardless of which install path was used.

Backups

By default, the existing client config is backed up before modification. Use --no-backup to skip.