Configuration

Registry: ~/.mux/servers.json

The registry declares all downstream MCP servers. It's hot-reloaded — edit and changes apply within 2 seconds.

{
  "servers": {
    "server-name": {
      "transport": "stdio | http",

      "command": "npx",
      "args": ["-y", "package-name"],
      "env": { "KEY": "${ENV_VAR}" },

      "url": "https://...",
      "headers": { "Authorization": "Bearer ${TOKEN}" },
      "auth": {
        "type": "oauth",
        "tokenEndpoint": "https://auth.example.com/oauth/token",
        "clientId": "client-id",
        "scopes": ["scope1", "scope2"]
      },

      "keywords": ["search", "terms"],
      "idleTimeoutMs": 300000
    }
  }
}

Field Reference

FieldTransportRequiredDescription
transportbothyes"stdio" or "http"
commandstdioyesCommand to spawn (e.g., npx, uvx, node)
argsstdionoCommand arguments array
envstdionoEnvironment variables (supports ${VAR} interpolation)
urlhttpyesMCP endpoint URL
headershttpnoStatic headers (supports ${VAR} interpolation)
authhttpnoOAuth config for browser-based authentication
keywordsbothnoSearch keywords (for discoverability)
idleTimeoutMsbothnoIdle timeout before kill (default: 5 min)

Environment Variable Interpolation

Use ${VAR_NAME} syntax in command, args, env, headers, and url fields. Mux reads from process.env at startup (including vars loaded from your shell profile).

{
  "command": "${GIT_COMMAND_PATH}",
  "env": {
    "GITLAB_TOKEN": "${GITLAB_TOKEN}",
    "API_URL": "${GITLAB_API_URL}"
  }
}

[!WARNING] If an env var is not set, it resolves to an empty string. Use mux-cli health to check for missing variables.

Environment Variables

VariableDefaultDescription
MUX_LOG_LEVELinfoerror | warn | info | debug
MUX_LOG_TO_FILEfalseSet true to write logs to ~/.mux/mux.log
MUX_REGISTRY_PATH~/.mux/servers.jsonPath to server registry
MUX_TOKEN_STORE_PATH~/.mux/tokens.jsonPath to OAuth token cache
MUX_DEFAULT_IDLE_TIMEOUT300000Default idle timeout in ms (5 min)