Skip to main content

Configuration

Broxy reads configuration from a directory containing mcp.json and one or more preset_<id>.json files. Changes are hot reloaded by the configuration watcher.

mcp.json​

The mcp.json file defines downstream servers and global timeouts.

{
  "requestTimeoutSeconds": 60,
  "capabilitiesTimeoutSeconds": 30,
  "capabilitiesRefreshIntervalSeconds": 300,
  "defaultPresetId": "developer",
  "inboundSsePort": 3335,
  "showTrayIcon": true,
  "mcpServers": {
    "search": {
      "name": "Search MCP",
      "transport": "streamable-http",
      "url": "https://mcp.example.com/stream",
      "headers": {
        "Authorization": "Bearer ${SEARCH_TOKEN}"
      }
    },
    "files": {
      "name": "File MCP",
      "transport": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-files-server.js"]
    }
  }
}

Supported keys​

  • mcpServers: Map of server IDs to downstream server definitions.
  • requestTimeoutSeconds: Timeout for MCP calls.
  • capabilitiesTimeoutSeconds: Timeout for tools/prompts/resources listing.
  • capabilitiesRefreshIntervalSeconds: Background refresh interval for cached capabilities.
  • defaultPresetId: Used by UI/stdio mode when no preset is provided.
  • inboundSsePort: Port for the local streamable HTTP inbound server (UI usage).
  • showTrayIcon: Toggle the desktop tray icon.

Transport definitions​

Each server entry declares a transport and the fields it needs:

  • stdio: requires command and optional args and env.
  • http or streamable-http: requires url and optional headers.
  • websocket/ws: requires url and optional headers.

Environment placeholders​

Broxy resolves ${ENV} and {ENV} placeholders in string values using the current environment. Missing variables fail the configuration load.

Preset files​

Presets live in preset_<id>.json files and define allow lists for tools, prompts, and resources.

{
  "id": "developer",
  "name": "Developer",
  "tools": [
    {"serverId": "files", "toolName": "readFile", "enabled": true},
    {"serverId": "files", "toolName": "writeFile", "enabled": true}
  ],
  "prompts": [
    {"serverId": "search", "promptName": "research", "enabled": true}
  ],
  "resources": [
    {"serverId": "files", "resourceKey": "workspace", "enabled": true}
  ]
}

Disabled entries can remain listed with enabled: false. Missing tools are logged as warnings and ignored.