Ultra uses a YAML configuration file to define upstream servers, observability settings, and Hub connection details.
Config Search Order
Ultra searches for configuration files in this order (first match wins):
ultra.yaml or ultra.yml (current directory).ultra.yaml or .ultra.yml (current directory)$XDG_CONFIG_HOME/ultra/config.yaml (default: ~/.config/ultra/config.yaml)$XDG_CONFIG_HOME/ultra/config.yml~/.ultra.yaml or ~/.ultra.yml
If no config file is found, Ultra uses sensible defaults.
Show Config Path
Default Config Path
~/.config/ultra/config.yaml
Full Example
version: "1"
server:
name: ultra
log_level: info # debug, info, warn, error
upstream:
filesystem:
command: npx
args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
enabled: true
description: "Local filesystem access"
github:
command: npx
args: ["-y", "@modelcontextprotocol/server-github"]
env:
GITHUB_TOKEN: "ghp_xxxxxxxxxxxx"
enabled: true
notion:
url: "https://mcp.notion.so"
headers:
Authorization: "Bearer secret_xxxxxxxxxxxx"
enabled: true
policy:
enabled: false # Not yet implemented
path: ""
observability:
enabled: false # Set to true for OTLP export
endpoint: "" # e.g., "localhost:4317"
service_name: ultra
hub:
enabled: false
url: "https://hub.ultra.security"
sync_interval: "60s"
offline_mode: false
Configuration Reference
server
| Field | Type | Default | Description |
|---|
name | string | "ultra" | Server name advertised to MCP clients |
log_level | string | "info" | Logging level: debug, info, warn, error |
upstream
A map of named upstream MCP servers. Each server uses either stdio transport (command) or HTTP transport (url).
| Field | Type | Required | Description |
|---|
command | string | For stdio | Command to execute |
args | string[] | No | Command arguments |
env | map | No | Environment variables |
url | string | For HTTP | HTTP URL for remote servers |
headers | map | No | HTTP headers (e.g., auth tokens) |
enabled | bool | No | Whether this server is active (default: false) |
description | string | No | Human-readable description |
Each upstream must specify either command or url, not both.
observability
| Field | Type | Default | Description |
|---|
enabled | bool | false | Enable OTLP telemetry export |
endpoint | string | "" | OTLP endpoint (e.g., localhost:4317) |
service_name | string | "ultra" | Service name for telemetry |
hub
| Field | Type | Default | Description |
|---|
enabled | bool | false | Enable Hub sync |
url | string | "https://hub.ultra.security" | Hub API URL |
gateway_id | string | | Assigned by Hub during linking |
sync_interval | string | "60s" | Sync frequency (e.g., "60s", "5m") |
offline_mode | bool | false | Allow operation without Hub connectivity |
deploy_key | string | | Static API key for CI/headless deployments |
Hub authentication tokens (access_token, refresh_token, token_expiry) are managed automatically by ultra login and should not be edited manually.
policy
| Field | Type | Default | Description |
|---|
enabled | bool | false | Enable policy evaluation |
path | string | "" | Path to policy files |
The policy engine is not yet implemented. This config block exists as a placeholder. See Roadmap: Policy Engine. File Permissions
The config file is saved with 0600 permissions (owner read/write only) because it may contain authentication tokens and API keys.
Programmatic Config Management
Use ultra config subcommands to modify configuration:
# Set an auth token for a server
ultra config set-token github-mcp-server YOUR_TOKEN
# Set a custom header
ultra config set-header my-server X-API-Key YOUR_KEY
# Show config file path
ultra config path
