> ## 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 Clients
> Set up your MCP clients 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 clients 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 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.
Once connected, you can manage, discover, and reconnect your MCP servers visually with the [`ultra_servers` MCP App](/getting-started/mcp-app), right inside your AI client.
## Interactive Wizard
Run the install wizard to be guided through the process:
```bash theme={null}
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:
```bash theme={null}
# 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](/installation/ona-setup) for the canonical setup.
Install into all detected clients:
```bash theme={null}
ultra install --all
```
## List Detected Clients
Preview which clients Ultra can detect without making changes:
```bash theme={null}
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.
Most clients 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 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:
```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 servers 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-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:
```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).
### 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 | `/.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 client** to load Ultra
2. Import existing MCP servers with `ultra migrate` (see [Migrate Servers](/installation/migrate-servers))
3. Or add new servers with `ultra search` and `ultra add`