Configuration files

Broxy uses file-based configuration under your home directory. The Desktop UI and CLI share the same files; the UI writes to them in the background, and the CLI watches for changes.

Default config directory:

• ~/.config/broxy

File list

• mcp.json: downstream servers and global settings.
• preset_<id>.json: preset allow lists.
• ui.json: UI-only settings (for example tray icon visibility).
• logs/YYYY-MM-DD.log: daily log files.
• icons/: custom server icons (Desktop UI).

OAuth tokens and dynamic client registration data for downstream HTTP/WS servers are stored in system secure storage (Keychain on macOS, Secret Service on Linux). If secure storage is unavailable, Broxy keeps OAuth state in memory for the current session only.

mcp.json responsibilities

mcp.json is the main configuration file:

• Defines downstream servers under mcpServers.
• Stores global settings:
• defaultPresetId
• inboundHttpPort
• requestTimeoutSeconds
• capabilitiesTimeoutSeconds
• authorizationTimeoutSeconds
• connectionRetryCount
• capabilitiesRefreshIntervalSeconds
• fallbackPromptsAndResourcesToTools
• adapterMode

Preset files

Preset files live next to mcp.json:

• File name must match the preset id: preset_<id>.json.
• Changing a preset file updates the running proxy without restart.

Hot reload behavior

While Broxy is running:

• Changes to mcp.json are detected automatically.
• Changes to preset_*.json are applied immediately.
• The inbound endpoint stays up while capabilities are re-synced.

Environment placeholders

Placeholders are supported in env and auth values:

• ${VAR}
• {VAR}

If a referenced variable is missing, Broxy reports a configuration error. When saving mcp.json, placeholders are preserved so resolved secrets are not written back to disk.