Configure Clients

Ultra works with Claude Desktop, Cursor, VS Code (including GitHub Copilot), Cline, Claude Code, Codex, Grok Build, Windsurf, Roo Code, Goose, OpenCode, Gemini CLI, Antigravity, LM Studio, Amazon Q Developer, Zed, Ona, and Hermes. After installing Ultra, configure your AI clients to route MCP traffic through it.

For Ona cloud dev environments, see the dedicated Ona setup guide within Agent Environments, which covers devcontainer-based automated installation.

Client
Terminal

Automatic Configuration

When you install Ultra using the downloaded installer, the Ultra Setup wizard launches automatically. It detects your installed AI clients and lets you select which ones to configure.

Ultra Setup wizard showing detected AI clients

Check the clients you want to configure and click Configure. Ultra updates each client’s settings so all MCP traffic routes through Ultra automatically.After setup:

Restart your AI client (e.g., quit and reopen Claude Desktop)
Start using your AI tools as usual — Ultra is now monitoring all MCP traffic in the background

You can re-run the setup wizard at any time from the Ultra application to add or reconfigure clients.

Once connected, you can manage, discover, and reconnect your MCP servers visually with the ultra_servers MCP App, right inside your AI client.

Interactive Wizard

Run the install wizard to be guided through the process:

ultra install

The wizard detects installed MCP clients, lets you choose which ones to configure, and sets Ultra as the MCP server in each client’s configuration.

Non-Interactive Mode

Install into a specific client:

# Claude Desktop
ultra install --client claude

# Cursor
ultra install --client cursor

# VS Code (native MCP)
ultra install --client vscode

# Cline (VS Code extension)
ultra install --client cline

# Claude Code
ultra install --client claude-code

# Windsurf
ultra install --client windsurf

# Goose
ultra install --client goose

# Codex
ultra install --client codex

# Grok Build
ultra install --client grok

# Gemini CLI
ultra install --client gemini

# Antigravity
ultra install --client antigravity

# Roo Code
ultra install --client roocode

# Amazon Q Developer
ultra install --client amazonq

# LM Studio
ultra install --client lmstudio

# Zed
ultra install --client zed

# OpenCode
ultra install --client opencode

# Hermes
ultra install --client hermes

# Skip confirmation
ultra install --client claude --yes

Ona uses a workspace-scoped devcontainer flow rather than a per-machine install. See the Ona setup guide for the canonical setup.

Install into all detected clients:

ultra install --all

List Detected Clients

Preview which clients Ultra can detect without making changes:

ultra install --list

This shows each client’s installation status, config path, and any existing MCP server configurations.

Flags

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

Run ultra doctor -v to verify that Ultra is correctly installed and your MCP clients are properly configured.

Supported Clients

Client	Auto-Install
Claude Desktop	Yes
Cursor	Yes
VS Code (incl. GitHub Copilot)	Yes
Cline	Yes
Claude Code	Yes
Windsurf	Yes
Goose	Yes
Codex	Yes
Grok Build	Yes
OpenCode	Yes
Gemini CLI	Yes
Antigravity	Yes
Roo Code	Yes
Amazon Q Developer	Yes
LM Studio	Yes
Zed	Yes
Ona	Yes
Hermes	Yes

All clients in the table are detected and configured automatically by ultra install.

GitHub Copilot does not have a separate config file. It reads MCP servers from VS Code’s mcp.json, so running ultra install --client vscode configures Ultra for both native VS Code MCP and Copilot. If the Copilot extension is detected, Ultra labels the client as VS Code + Copilot in the setup wizard.

What It Does

When you configure a client (either through the setup wizard or CLI), Ultra registers itself as an MCP server in the client’s configuration file. The client then launches Ultra via ultra start whenever it needs MCP tools. Ultra in turn connects to your configured upstream servers.

Technical details

Most clients use JSON with an mcpServers key:

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

VS Code native MCP uses a servers key:

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

Goose uses YAML with an extensions key:

extensions:
  ultra:
    cmd: /usr/local/bin/ultra
    args:
      - start
    type: stdio
    enabled: true

Codex uses TOML:

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

Grok Build uses the same TOML mcp_servers format as Codex, in ~/.grok/config.toml:

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

Ultra overlays only the fields it models onto each server entry, so Grok-specific keys such as startup_timeout_sec, tool_timeout_sec, and bearer_token_env_var are preserved.OpenCode uses JSON with an mcp key:

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

Zed uses JSON with a context_servers key, embedded in the editor’s main settings.json. Custom stdio servers are marked with "source": "custom":

{
  "context_servers": {
    "ultra": {
      "source": "custom",
      "command": "/usr/local/bin/ultra",
      "args": ["start"]
    }
  }
}

Zed’s settings.json is JSONC, so it ships pre-populated with // comments and trailing commas. Ultra edits the context_servers key in place, preserving your other settings, comments, and any per-server fields it does not model. If the file can’t be parsed as JSONC, Ultra refuses to write rather than risk corrupting it.

Hermes uses YAML with an mcp_servers key:

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

Antigravity uses the standard mcpServers JSON format. It intentionally stores its MCP config under the shared .gemini directory (in config/mcp_config.json), separate from the Gemini CLI’s own settings.json.Ona uses the standard mcpServers JSON format, scoped to the workspace (the file lives inside the project checkout, not at a global path).

Client Config Paths

Client	macOS	Windows	Linux
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json`	`%APPDATA%\Claude\claude_desktop_config.json`	`~/.config/Claude/claude_desktop_config.json`
Cursor	`~/.cursor/mcp.json`	`~/.cursor/mcp.json`	`~/.cursor/mcp.json`
VS Code	`~/Library/Application Support/Code/User/mcp.json`	`%APPDATA%\Code\User\mcp.json`	`~/.config/Code/User/mcp.json`
Cline	`~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`	`%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`	`~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
Claude Code	`~/.claude.json`	`~/.claude.json`	`~/.claude.json`
Windsurf	`~/.codeium/windsurf/mcp_config.json`	`~/.codeium/windsurf/mcp_config.json`	`~/.codeium/windsurf/mcp_config.json`
Goose	`~/.config/goose/config.yaml`	`%APPDATA%\goose\config.yaml`	`~/.config/goose/config.yaml`
Codex	`~/.codex/config.toml`	`~/.codex/config.toml`	`~/.codex/config.toml`
Grok Build	`~/.grok/config.toml`	`~/.grok/config.toml`	`~/.grok/config.toml`
OpenCode	`~/.config/opencode/opencode.json`	`%APPDATA%\opencode\opencode.json`	`~/.config/opencode/opencode.json`
Gemini CLI	`~/.gemini/settings.json`	`~/.gemini/settings.json`	`~/.gemini/settings.json`
Antigravity	`~/.gemini/config/mcp_config.json`	`%USERPROFILE%\.gemini\config\mcp_config.json`	`~/.gemini/config/mcp_config.json`
Roo Code	`~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json`	`%APPDATA%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\cline_mcp_settings.json`	`~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json`
Amazon Q Developer	`~/.aws/amazonq/mcp.json`	`~/.aws/amazonq/mcp.json`	`~/.aws/amazonq/mcp.json`
LM Studio	`~/.lmstudio/mcp.json`	`~/.lmstudio/mcp.json`	`~/.lmstudio/mcp.json`
Zed	`~/.config/zed/settings.json`	`%APPDATA%\Zed\settings.json`	`~/.config/zed/settings.json`
Ona	`<workspace>/.ona/mcp-config.json`	`<workspace>\.ona\mcp-config.json`	`<workspace>/.ona/mcp-config.json`
Hermes	`~/.hermes/config.yaml`	`~/.hermes/config.yaml`	`~/.hermes/config.yaml`

Ultra stores its own configuration in ~/.config/ultra/config.yaml. See Configuration for details.

After Configuration

Restart your MCP client to load Ultra
Import existing MCP servers with ultra migrate (see Migrate Servers)
Or add new servers with ultra search and ultra add

Getting Started

Ultra Hub

Observability

Concepts

Configure Clients

Automatic Configuration

Interactive Wizard

Non-Interactive Mode

List Detected Clients

Flags

Supported Clients

What It Does

Client Config Paths

After Configuration

​Automatic Configuration

​Interactive Wizard

​Non-Interactive Mode

​List Detected Clients

​Flags

​Supported Clients

​What It Does

​Client Config Paths

​After Configuration

Automatic Configuration

Interactive Wizard

Non-Interactive Mode

List Detected Clients

Flags

Supported Clients

What It Does

Client Config Paths

After Configuration