> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ultra.security/llms.txt
> Use this file to discover all available pages before exploring further.
# Configure Agents
> Set up your MCP agents to use Ultra
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](/installation/agent-environments), which covers devcontainer-based automated installation.
## 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.
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:
1. **Restart your AI agent** (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 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:
```bash theme={null}
# 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`](/cli/config) for details.
Once connected, you can manage, discover, and reconnect your MCP connectors visually with the [`ultra_servers` MCP App](/getting-started/mcp-app), right inside your AI agent.
## Interactive Wizard
Run the install wizard to be guided through the process:
```bash theme={null}
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:
```bash theme={null}
# 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](/installation/ona-setup) for the canonical setup.
Install into all detected agents:
```bash theme={null}
ultra install --all
```
## List Detected Agents
Preview which agents Ultra can detect without making changes:
```bash theme={null}
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.
Most agents use JSON with an `mcpServers` key:
```json theme={null}
{
"mcpServers": {
"ultra": {
"command": "/usr/local/bin/ultra",
"args": ["start"]
}
}
}
```
VS Code native MCP uses a `servers` key:
```json theme={null}
{
"servers": {
"ultra": {
"command": "/usr/local/bin/ultra",
"args": ["start"]
}
}
}
```
Goose uses YAML with an `extensions` key:
```yaml theme={null}
extensions:
ultra:
cmd: /usr/local/bin/ultra
args:
- start
type: stdio
enabled: true
```
Codex uses TOML:
```toml theme={null}
[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`:
```toml theme={null}
[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:
```json theme={null}
{
"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"`:
```json theme={null}
{
"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:
```yaml theme={null}
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 | `/.ona/mcp-config.json` | `\.ona\mcp-config.json` | `/.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](/configuration/config-file) for details.
## After Configuration
1. **Restart your MCP agent** to load Ultra
2. Import existing MCP connectors with `ultra migrate` (see [Migrate Connectors](/installation/migrate-connectors))
3. Or add new connectors with `ultra search` and `ultra add`