CLI

Reference

Sub Commands

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.

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:
  Copy

  ./toolbox --allowed-hosts="localhost,127.0.0.1"
  

{{< notice 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. {{< /notice >}}

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:
  Copy

  ./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:
  Copy

  ./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

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'). See Prebuilt Tools Reference for allowed values.

{{< notice 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. {{< /notice >}}

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.