Configure Agents

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 agents 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.

Agent
Terminal

Automatic Configuration

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

Ultra Setup wizard showing detected AI agents

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

Restart your AI agent (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 agents.

Automatically configure new agents

The wizard also offers an Automatically configure all AI apps checkbox (“Includes apps you install later.”). It’s unchecked by default. When you check it and confirm, Ultra keeps itself installed in every supported agent it detects going forward, including ones you install after this setup finishes, without touching that agent’s other MCP connectors or taking ownership of its config.To turn it back off, re-run the wizard and uncheck the box. If enforcement is set to one of the advanced modes, the dialog shows a short note in place of the checkbox. The same setting is available from the terminal:

# Equivalent to checking the box
ultra config set drift-enforcement auto_install

# Equivalent to unchecking it
ultra config set drift-enforcement default

# Check the current value
ultra config get drift-enforcement

See ultra config for details.Once connected, you can manage, discover, and reconnect your MCP connectors visually with the ultra_servers MCP App, right inside your AI agent.

Interactive Wizard

Run the install wizard to be guided through the process:

ultra install

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

Non-Interactive Mode

Install into a specific agent:

# Claude Desktop
ultra install --agent claude

# Cursor
ultra install --agent cursor

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

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

# Claude Code
ultra install --agent claude_code

# Windsurf
ultra install --agent windsurf

# Goose
ultra install --agent goose

# Codex
ultra install --agent codex

# Grok Build
ultra install --agent grok

# Gemini CLI
ultra install --agent gemini

# Antigravity
ultra install --agent antigravity

# Roo Code
ultra install --agent roocode

# Amazon Q Developer
ultra install --agent amazonq

# LM Studio
ultra install --agent lmstudio

# Zed
ultra install --agent zed

# OpenCode
ultra install --agent opencode

# Hermes
ultra install --agent hermes

# Skip confirmation
ultra install --agent 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 agents:

ultra install --all

List Detected Agents

Preview which agents Ultra can detect without making changes:

ultra install --list

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

Flags

Flag	Short	Default	Description
`--agent`			Target agent (`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 agents
`--config`			Path to Ultra config file
`--no-backup`		`false`	Skip backup of existing config
`--yes`	`-y`	`false`	Skip confirmation prompt (used with `--agent`)
`--list`	`-l`	`false`	List detected agents

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

Supported Agents

Agent	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 agents in the table are detected and configured automatically by ultra install.

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

What It Does

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

Technical details

Most agents 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 connector 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 connectors 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-connector 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).

Agent Config Paths

Agent	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 agent to load Ultra
Import existing MCP connectors with ultra migrate (see Migrate Connectors)
Or add new connectors with ultra search and ultra add

Getting Started

Ultra Hub

Observability

Concepts

Configure Agents

Automatic Configuration

Automatically configure new agents

Interactive Wizard

Non-Interactive Mode

List Detected Agents

Flags

Supported Agents

What It Does

Agent Config Paths

After Configuration

​Automatic Configuration

​Automatically configure new agents

​Interactive Wizard

​Non-Interactive Mode

​List Detected Agents

​Flags

​Supported Agents

​What It Does

​Agent Config Paths

​After Configuration

Automatic Configuration

Automatically configure new agents

Interactive Wizard

Non-Interactive Mode

List Detected Agents

Flags

Supported Agents

What It Does

Agent Config Paths

After Configuration