MCP Toolbox for Databases security: what to configure before an agent touches your data

The short answer

MCP Toolbox for Databases is Google’s open source MCP server for databases, configured with a tools.yaml file of sources, tools and toolsets.¹ It’s safe when you use it the way it’s designed: custom tools with fixed, parameterised SQL. It’s risky when you start it with --prebuilt and hand an agent execute_sql, which runs any statement the agent writes. Toolbox’s own docs say that tool “is intended for developer assistant workflows with human-in-the-loop and shouldn’t be used for production agents.”²

Toolbox has a strong read-only mode, but its engine-level lock is documented for four Google Cloud engines (Cloud SQL for PostgreSQL and MySQL, AlloyDB and BigQuery).⁴ For a self-hosted Postgres source, connect with a read-only database role as well.

What Toolbox is

Toolbox sits between an MCP client (an IDE, Claude, an agent framework) and your databases. It handles connections and exposes tools. The project is Apache-2.0 licensed, and its docs are at version 1.15.0 as of this writing.¹ It supports Google Cloud databases and many others, including PostgreSQL, MySQL, SQL Server, MongoDB and Snowflake.¹

A configuration has three main parts:

It also emits OpenTelemetry traces and metrics¹, which helps you see which tools an agent called, though not what each call changed in the database.

Custom tools vs prebuilt execute_sql

This is the decision that matters most.

Custom tools fix the SQL in the config file. The agent supplies only parameter values:

Code A settings file: the rules a tool reads before it acts.

kind: tool
name: search-hotels-by-name
type: mysql-sql
source: my-mysql-source
description: Search hotels by name.
parameters:
  - name: name
    type: string
statement: SELECT * FROM hotels WHERE name LIKE CONCAT('%', ?, '%');

The agent can search hotels by name. It can’t drop the table, read another table, or update anything, because no statement that does those things exists in the config. That is a real tool-call policy: the allowed actions are the listed ones.

Prebuilt tools are the quick start. Running Toolbox with --prebuilt=<database> loads standard tools such as list_tables and execute_sql.¹ postgres-execute-sql takes a single sql parameter and runs it.² Whatever the database user can do, the agent can now do.

Use prebuilt tools to explore a dev database from your IDE. For an agent that runs unattended or near production data, write custom tools.

Read-only mode, and where it applies

Toolbox’s read-only feature is better than most. Setting readOnly: true on a source enables what its docs call an immutable protocol-level lock, and how it’s enforced depends on the engine:⁴

In read-only mode Toolbox also removes write tools from the catalog and marks the exposed ones with readOnlyHint: true.⁴ Prebuilt servers take environment variables such as CLOUD_SQL_POSTGRES_READONLY=true.⁴

The important detail is the table’s length. A plain postgres source pointing at your own server, Neon, Supabase or RDS isn’t in that enforcement list.⁴ For those, read-only has to come from the database: a role with SELECT grants and nothing else. A read-only transaction opened by the tool layer can be escaped, as the Postgres MCP read-only bypass showed, and a session setting the role can change isn’t enough either. Our read-only Postgres role comparison shows how to build one.

Also remember that readOnlyHint is a hint to the client.⁴ Clients may use it to skip a confirmation step, so make sure the hint is true before you rely on it.

Authentication and per-user data

Toolbox has its own auth services, google (Google Sign-In) and generic (any OIDC provider).³ They give you two useful controls:

• Authorized invocation. A tool with authRequired only runs for callers with a valid token; Toolbox rejects calls that fail to validate.³
• Authenticated parameters. A parameter’s value comes from a claim in the caller’s ID token instead of from the model.³

The second is the one to use for per-user data. If a tool’s statement is SELECT * FROM orders WHERE user_id = ? and that ? is filled from the signed token, the agent can’t ask for someone else’s orders by changing an argument, because it never supplies the argument. That closes a common hole in agent tools, where the model is trusted to pass the right user id.

Toolbox can also protect the whole MCP endpoint with MCP Authorization (mcpEnabled: true), but only with the generic auth type.³ Our MCP server security basics cover where that layer fits.

What Toolbox doesn’t do

Toolbox is a well-designed tool layer. Like any tool layer, it has edges:

• It doesn’t check results. If an agent calls an update tool, Toolbox runs it. Whether one row or ten thousand changed is up to your statement and your data.
• It doesn’t add approvals. Human review of a risky call happens in the MCP client, if the client offers it.
• It’s only as narrow as the database user. With execute_sql, the source credentials are the real limit. A source configured with an owner or admin user gives the agent an owner or admin.
• Engine-level read-only covers four engines in its docs.⁴

None of these are criticisms. They’re the boundaries of what an MCP server can know. The checks that matter for writes, such as approval before risky calls and a read-back after, sit beside it. Our best Postgres MCP server comparison puts Toolbox’s approach next to others.

A setup checklist

1. Prefer custom SQL tools with fixed statements over --prebuilt for any agent you don’t watch call by call.²
2. Give each source its own database user with the narrowest grants that work.
3. Turn on readOnly: true where it’s enforced; for other Postgres sources, use a SELECT-only role as well.⁴
4. Use authenticated parameters for any per-user lookup.³
5. Require auth on tools that read sensitive data or write anything.³
6. Group tools into toolsets per agent, so each agent loads only what it needs.¹
7. Send OpenTelemetry to your tracing backend, and keep a separate record of what writes changed.¹

To try approvals and read-backs on a real database in your browser, open the playground. To grade which database tools and credentials your coding agents can reach on your own machine, run npx deedglass scan (the grade, explained).

Written with AI assistance and checked against our claims register.