Configuration File

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

ultra 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

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 enforcement

Policy enforcement is not configured in this file. Guardrails and governance rules are configured in Ultra Hub and synced automatically to every connected gateway, so enforcement stays consistent across your fleet without editing local config.

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

Getting Started

Ultra Hub

Observability

Concepts

Configuration File

Config Search Order

Show Config Path

Default Config Path

Full Example

Configuration Reference

`server`

`upstream`

`observability`

`hub`

Policy enforcement

File Permissions

Programmatic Config Management

​Config Search Order

​Show Config Path

​Default Config Path

​Full Example

​Configuration Reference

​server

​upstream

​observability

​hub

​Policy enforcement

​File Permissions

​Programmatic Config Management

Config Search Order

Show Config Path

Default Config Path

Full Example

Configuration Reference

`server`

`upstream`

`observability`

`hub`

Policy enforcement

File Permissions

Programmatic Config Management