CLI

This page describes the toolbox command-line options.

Reference

Flag (Short)Flag (Long)DescriptionDefault
-a--addressAddress of the interface the server will listen on.127.0.0.1
--disable-reloadDisables dynamic reloading of tools file.
-h--helphelp for toolbox
--log-levelSpecify the minimum level logged. Allowed: ‘DEBUG’, ‘INFO’, ‘WARN’, ‘ERROR’.info
--logging-formatSpecify logging format to use. Allowed: ‘standard’ or ‘JSON’.standard
-p--portPort the server will listen on.5000
--prebuiltUse a prebuilt tool configuration by source type. Cannot be used with –tools-file. See Prebuilt Tools Reference for allowed values.
--stdioListens via MCP STDIO instead of acting as a remote HTTP server.
--telemetry-gcpEnable exporting directly to Google Cloud Monitoring.
--telemetry-otlpEnable exporting using OpenTelemetry Protocol (OTLP) to the specified endpoint (e.g. ‘http://127.0.0.1:4318’)
--telemetry-service-nameSets the value of the service.name resource attribute for telemetry data.toolbox
--tools-fileFile path specifying the tool configuration. Cannot be used with –prebuilt, –tools-files, or –tools-folder.
--tools-filesMultiple file paths specifying tool configurations. Files will be merged. Cannot be used with –prebuilt, –tools-file, or –tools-folder.
--tools-folderDirectory path containing YAML tool configuration files. All .yaml and .yml files in the directory will be loaded and merged. Cannot be used with –prebuilt, –tools-file, or –tools-files.
--uiLaunches the Toolbox UI web server.
-v--versionversion for toolbox

Examples

Transport Configuration

Server Settings:

  • --address, -a: Server listening address (default: “127.0.0.1”)
  • --port, -p: Server listening port (default: 5000)

STDIO:

  • --stdio: Run in MCP STDIO mode instead of HTTP server

Usage Examples

# Basic server with custom port configuration
./toolbox --tools-file "tools.yaml" --port 8080

Tool Configuration Sources

The CLI supports multiple mutually exclusive ways to specify tool configurations:

Single File: (default)

  • --tools-file: Path to a single YAML configuration file (default: tools.yaml)

Multiple Files:

  • --tools-files: Comma-separated list of YAML files to merge

Directory:

  • --tools-folder: Directory containing YAML files to load and merge

Prebuilt Configurations:

  • --prebuilt: Use predefined configurations for specific database types (e.g., ‘bigquery’, ‘postgres’, ‘spanner’). See Prebuilt Tools Reference for allowed values.

Tip

The CLI enforces mutual exclusivity between configuration source flags, preventing simultaneous use of --prebuilt with file-based options, and ensuring only one of --tools-file, --tools-files, or --tools-folder is used at a time.

Hot Reload

Toolbox enables dynamic reloading by default. To disable, use the --disable-reload flag.

Toolbox UI

To launch Toolbox’s interactive UI, use the --ui flag. This allows you to test tools and toolsets with features such as authorized parameters. To learn more, visit Toolbox UI.