Reference on MCP Toolbox for Databases

CLI

Mon, 01 Jan 0001 00:00:00 +0000

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 config.
`-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`
	`--mcp-prm-file`	Path to a manual Protected Resource Metadata (PRM) JSON file. If provided, overrides auto-generation for MCP Server-Wide Authentication.
`-p`	`--port`	Port the server will listen on.	`5000`
	`--prebuilt`	Use one or more prebuilt tool configuration by source type. 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`
	`--config`	File path specifying the tool configuration. Cannot be used with –configs or –config-folder.
	`--configs`	Multiple file paths specifying tool configurations. Files will be merged. Cannot be used with –config or –config-folder.
	`--config-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 –config or –configs.
	`--ui`	Launches the Toolbox UI web server.
	`--allowed-origins`	Specifies a list of origins permitted to access this server for CORs access.	`*`
	`--allowed-hosts`	Specifies a list of hosts permitted to access this server to prevent DNS rebinding attacks.	`*`
	`--user-agent-metadata`	Appends additional metadata to the User-Agent.
	`--poll-interval`	Specifies the polling frequency (seconds) for configuration file updates.	`0`
`-v`	`--version`	version 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.

FAQ

Mon, 01 Jan 0001 00:00:00 +0000

How can I deploy or run Toolbox?

MCP Toolbox for Databases is open-source and can be run or deployed to a multitude of environments. For convenience, we release compiled binaries and docker images (but you can always compile yourself as well!).

For detailed instructions, check out these resources:

Do I need a Google Cloud account/project to get started with Toolbox?

Nope! While some of the sources Toolbox connects to may require GCP credentials, Toolbox doesn’t require them and can connect to a bunch of different resources that don’t.

Style Guide

Mon, 01 Jan 0001 00:00:00 +0000

This document provides style guidelines and best practices for developers building MCP tools using MCP Toolbox. Following these standards ensures that agents can reason effectively, security is maintained, and user intent is met with high precision.

Combatting “Context Rot” and Tool Limits

Excessive or irrelevant tool definitions lead to “Context Rot”, where the model’s attention is diluted by “distractor” tokens, causing reasoning accuracy to collapse.

Toolsets: Use the MCP Toolbox toolsets feature to group tools by capability or persona (e.g., cloud-sql-admin vs. cloud-sql-data). This ensures the agent only sees tools relevant to its immediate intent.
Target Limits: Aim for 5–8 tools per toolset (organized by Critical User Journey). While the platform supports more, performance and accuracy are highest when the agent is exposed to a cognitively manageable list of actions. The current rule of thumb is to try to keep it to 40 tools per server as an upper limit, though even this amount may cause performance issues. Performance degrades as more tools are added, so teams should heavily weigh adding new tools against the negative impact on tool accuracy until other mechanisms are in place to deal with this.

Naming Conventions

Tool Names

Use snake_case with the pattern <action>_<resource>. Avoid product-specific prefixes, as agents can disambiguate tools by the MCP server name.

Versioning Policy

Mon, 01 Jan 0001 00:00:00 +0000

MCP Toolbox for Databases follows Semantic Versioning.

Definition of the Public API

For the purposes of this policy, the “Public API” includes:

Server
- CLI: The execution engine and lifecycle manager for tool hosting.
- Configuration Manifests: The structural specification of tools.yaml.
- Pre-built Configs: Curated sets of tools (and other MCP primitives) including the CLI flag, source configuration, toolsets names, and tools.
- MCP versions: Supporting MCP revisions and transport protocols.
Client SDKs: Both the foundational “Base SDKs” and the orchestration-specific “Integrated SDKs”.

What Constitutes a Breaking Change (Major Version Bump)

A major version bump (e.g., v1.x.x to v2.0.0) is required for the following modifications: