Configure Clients

Set up your MCP clients to use Ultra

Ultra works with Claude Desktop, Cursor, VS Code (including GitHub Copilot), Cline, Claude Code, Codex, Windsurf, Roo Code, Goose, OpenCode, Gemini CLI, LM Studio, Amazon Q Developer, 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

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.

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:

1. Restart your AI client (e.g., quit and reopen Claude Desktop)
2. 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.

Terminal

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

# Gemini CLI
ultra install --client gemini

# Roo Code
ultra install --client roocode

# Amazon Q Developer
ultra install --client amazonq

# LM Studio
ultra install --client lmstudio

# 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, opencode, gemini, roocode, amazonq, lmstudio, 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
OpenCode	Yes
Gemini CLI	Yes
Roo Code	Yes
Amazon Q Developer	Yes
LM Studio	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"]

OpenCode uses JSON with an mcp key:

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

Hermes uses YAML with an mcp_servers key:

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

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
OpenCode	~/.config/opencode/opencode.json	%APPDATA%\opencode\opencode.json	~/.config/opencode/opencode.json
Gemini CLI	~/.gemini/settings.json	~/.gemini/settings.json	~/.gemini/settings.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
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

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