CLI

This page describes the toolbox command-line options.

  6 minute read  

Reference

Flag (Short)Flag (Long)DescriptionDefault
-a--addressAddress of the interface the server will listen on.127.0.0.1
--disable-reloadDisables dynamic reloading config.
-h--helphelp for toolbox
--http-max-request-bytesMaximum MCP HTTP request body size in bytes.10485760
--ignore-unknown-toolsLog warnings and skip unknown/unsupported tool types instead of failing to start.
--log-levelSpecify the minimum level logged. Allowed: ‘DEBUG’, ‘INFO’, ‘WARN’, ‘ERROR’.info
--logging-formatSpecify logging format to use. Allowed: ‘standard’ or ‘JSON’.standard
--mcp-prm-filePath to a manual Protected Resource Metadata (PRM) JSON file. If provided, overrides auto-generation for MCP Server-Wide Authentication.
-p--portPort the server will listen on.5000
--tls-certPath to the PEM-encoded TLS certificate file.
--tls-keyPath to the PEM-encoded TLS private key file.
--prebuiltUse one or more prebuilt tool configuration by source type. Optionally specify a toolset suffix (e.g., <source>/<toolset>) to load only that toolset. 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-gcp-projectGoogle Cloud project ID used for --telemetry-gcp; defaults to GOOGLE_CLOUD_PROJECT if not set.
--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
--sql-commenterAppend SQLCommenter-format comments (traceparent, server, tool.name, db.system.name, client metadata from _meta["dev.mcp-toolbox/telemetry"]) to executed SQL.
--configFile path specifying the tool configuration. Cannot be used with –configs or –config-folder.
--configsMultiple file paths specifying tool configurations. Files will be merged. Cannot be used with –config or –config-folder.
--config-folderDirectory path containing YAML tool configuration files. All .yaml and .yml files in the directory will be loaded and merged. Cannot be used with –config or –configs.
--uiLaunches the Toolbox UI web server.
--allowed-originsSpecifies a list of origins permitted to access this server for CORs access.*
--allowed-hostsSpecifies a list of hosts permitted to access this server to prevent DNS rebinding attacks.*
--user-agent-metadataAppends additional metadata to the User-Agent.
--poll-intervalSpecifies the polling frequency (seconds) for configuration file updates.0
-v--versionversion for toolbox

Sub Commands

invoke

Executes a tool directly with the provided parameters. This is useful for testing tool configurations and parameters without needing a full client setup.

Syntax:

toolbox invoke <tool-name> [params]

Arguments:

  • tool-name: The name of the tool to execute (as defined in your configuration).
  • params: (Optional) A JSON string containing the parameters for the tool.

For more detailed instructions, see Invoke Tools via CLI.

skills-generate

Generates a skill package from a specified toolset. Each tool in the toolset will have a corresponding Node.js execution script in the generated skill.

Syntax:

toolbox skills-generate --name <name> --description <description> --toolset <toolset> --output-dir <output>

Flags:

  • --name: Name of the generated skill. When multiple toolsets are generated because --toolset is omitted, this name acts as a prefix for each skill folder (e.g., <name>-<toolset>).
  • --description: Description of the generated skill.
  • --toolset: (Optional) Name of the toolset to convert into a skill. If not provided, one skill will be generated for every custom toolset defined. If no custom toolsets are defined, it defaults to a single skill containing all tools.
  • --output-dir: (Optional) Directory to output generated skills (default: “skills”).
  • --license-header: (Optional) Optional license header to prepend to generated node scripts.
  • --additional-notes: (Optional) Additional notes to add under the Usage section of the generated SKILL.md.
  • --invocation-mode: (Optional) Invocation mode for the generated scripts: ‘binary’ or ’npx’ (default: “npx”).
  • --toolbox-version: (Optional) Version of @toolbox-sdk/server to use for npx approach (defaults to current toolbox version).

For more detailed instructions, see Generate Agent Skills.

Examples

Hardening Toolbox

Toolbox is designed for flexibility, but security should not be ignored—even in local development. When exposing the server to a network or running it alongside a web browser, use these configurations to protect your data and system.

Host Validation & DNS Rebinding Protection

The --allowed-hosts flag controls which Host headers the server accepts. Restricting this is the primary defense against DNS Rebinding attacks.

  • Flag: --allowed-hosts
  • Local Development: Set to localhost or 127.0.0.1.
  • Production: Set to your specific FQDN (e.g., toolbox.example.com).
  • Example:
    ./toolbox --allowed-hosts="localhost,127.0.0.1"

Tip

The “Local” Fallacy: Using --allowed-hosts="*" is unsafe even on localhost. A malicious website can trick your browser into making requests to 127.0.0.1, effectively bypassing the browser’s security to control your local Toolbox.

Cross-Origin Resource Sharing (CORS)

The --allowed-origins flag dictates which web applications (frontends) are permitted to communicate with your Toolbox API.

  • Flag: --allowed-origins
  • Recommendation: Avoid * in any environment containing sensitive data. Explicitly list your trusted frontend URLs.
  • Example:
    ./toolbox --allowed-origins="https://my-mcp-ui.internal.com"

Transport Layer Security (TLS/HTTPS)

By default, traffic is unencrypted (HTTP). In production or shared networks, you must enable TLS to prevent Man-in-the-Middle (MitM) attacks and packet sniffing.

  • Flag: --tls-cert and --tls-key (Both cert and key files are required for TLS activation)
  • Protocol: Toolbox enforces TLS 1.2 as a minimum version to ensure modern encryption standards.
  • Use Case: Use Certbot for public domains or mkcert for locally-trusted development certificates.
  • Example:
    ./toolbox --tls-cert=cert.pem --tls-key=key.pem

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 --config "tools.yaml" --port 8080

# Server with prebuilt + custom tools configurations
./toolbox --config tools.yaml --prebuilt alloydb-postgres

# Server with multiple prebuilt tools configurations
./toolbox --prebuilt alloydb-postgres,alloydb-postgres-admin
# OR
./toolbox --prebuilt alloydb-postgres --prebuilt alloydb-postgres-admin

# Server filtering a prebuilt configuration to load only a specific toolset
./toolbox --prebuilt alloydb-postgres/monitor

Tool Configuration Sources

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

Single File: (default)

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

Multiple Files:

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

Directory:

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

Prebuilt Configurations:

  • --prebuilt: Use one or more predefined configurations for specific database types (e.g., ‘bigquery’, ‘postgres’, ‘spanner’), optionally appending a toolset name to filter the loaded tools (e.g., alloydb-postgres/monitor). See Prebuilt Tools Reference for allowed values.

Tip

The CLI enforces mutual exclusivity between configuration source flags, preventing simultaneous use of the file-based options ensuring only one of --config, --configs, or --config-folder is used at a time.

Hot Reload

Toolbox supports two methods for detecting configuration changes: Push (event-driven) and Poll (interval-based). To completely disable all hot reloading, use the --disable-reload flag.

  • Push (Default): Toolbox uses a highly efficient push system that listens for instant OS-level file events to reload configurations the moment you save.
  • Poll (Fallback): Alternatively, you can use the --poll-interval=<seconds> flag to actively check for updates at a set cadence. Unlike the push system, polling “pulls” the file status manually, which is a great fallback for network drives or container volumes where OS events might get dropped. Set the interval to 0 to disable the polling system.

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.



Last modified June 18, 2026: chore(main): release 1.5.0 (#3379) (45c0f86)