genai-toolbox/docs/en/reference/cli.md at 0e7fbf465c488397aa9d8cab2e55165fff4eb53c

mirror of https://github.com/googleapis/genai-toolbox.git synced 2026-01-31 02:08:23 -05:00

Files

Yuan Teoh 862868f284 feat: add allowed-origins flag (#1984 )

Support `allowed-origins` flag to allow secure deployment of Toolbox.
Current Toolbox is **insecure by default**, which allows all origin
(`*`). This PR also updated docs to notify user of the new
`allowed-origins` flag in the Cloud Run, kubernetes, and docker
deployment docs.

This PR was tested manually by mocking a browser access:
1. Created a HTML file with Javascript fetch named
`malicious-client.html`:
```
<!DOCTYPE html>
<html>
<head>
    <title>Malicious CORS Test</title>
</head>
<body>
    <h1>Attempting to access API at http://127.0.0.1:5000/mcp</h1>
    <p>Check the **Chrome Developer Console** (F12 -> Console tab) for the result.</p>

    <script>
        fetch('http://127.0.0.1:5000/mcp', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                // The browser automatically adds the 'Origin' header based on where this HTML is served from (http://localhost:8000)
            },
            body: JSON.stringify({
                "jsonrpc": "2.0",
                "id": 1,
                "method": "tools/list"
            })
        })
        .then(response => {
            console.log('Success (but check console for CORS enforcement details):', response);
            return response.json();
        })
        .then(data => console.log('Data received (only if CORS passes):', data))
        .catch(error => console.error('Fetch Error:', error));
    </script>

</body>
</html>
```
2. Run `python3 -m http.server 8000`
3. Open `http://localhost:8000/malicious-client.html` in browser.
4. Tried without `--allowed-origins` flag -- success.
     Tried with `--allowed-origins=http://localhost:8000` -- success.
     Tried with `--allowed-origins=http://foo.com` -- unsuccessful.

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Averi Kitsch <akitsch@google.com>

2025-11-27 17:03:53 +00:00

6.4 KiB

Raw Blame History

title, type, weight, description

title	type	weight	description
CLI	docs	1	This page describes the `toolbox` command-line options.

Reference

Flag (Short)	Flag (Long)	Description	Default
`-a`	`--address`	Address of the interface the server will listen on.	`127.0.0.1`
	`--disable-reload`	Disables dynamic reloading of tools file.
`-h`	`--help`	help for toolbox
	`--log-level`	Specify the minimum level logged. Allowed: 'DEBUG', 'INFO', 'WARN', 'ERROR'.	`info`
	`--logging-format`	Specify logging format to use. Allowed: 'standard' or 'JSON'.	`standard`
`-p`	`--port`	Port the server will listen on.	`5000`
	`--prebuilt`	Use a prebuilt tool configuration by source type. Cannot be used with --tools-file. See Prebuilt Tools Reference for allowed values.
	`--stdio`	Listens via MCP STDIO instead of acting as a remote HTTP server.
	`--telemetry-gcp`	Enable exporting directly to Google Cloud Monitoring.
	`--telemetry-otlp`	Enable exporting using OpenTelemetry Protocol (OTLP) to the specified endpoint (e.g. 'http://127.0.0.1:4318')
	`--telemetry-service-name`	Sets the value of the service.name resource attribute for telemetry data.	`toolbox`
	`--tools-file`	File path specifying the tool configuration. Cannot be used with --prebuilt, --tools-files, or --tools-folder.
	`--tools-files`	Multiple file paths specifying tool configurations. Files will be merged. Cannot be used with --prebuilt, --tools-file, or --tools-folder.
	`--tools-folder`	Directory 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.
	`--ui`	Launches the Toolbox UI web server.
	`--allowed-origins`	Specifies a list of origins permitted to access this server.	`*`
`-v`	`--version`	version 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.

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

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.

6.4 KiB Raw Blame History