# MCP Toolbox for Databases: a Go MCP server that sits between your agent and your SQL

> MCP Toolbox for Databases is an Apache-2.0 Go server from googleapis that exposes prebuilt or hand-written database tools over the Model Context Protocol. It is convenient for IDE and agent access, but the prebuilt tools are generic by design, so production use means writing your own toolset.

**googleapis/mcp-toolbox** — MCP Toolbox for Databases is an open source MCP server for databases.

- Repository: https://github.com/googleapis/mcp-toolbox
- Website: https://mcp-toolbox.dev/documentation/introduction/
- Stars: 16,541 · Forks: 1,745
- Language: Go
- License: Apache-2.0
- Published: 2026-09-09 · Updated: 2026-09-09 · Language: en
- Canonical page: https://hysenlabs.com/projects/googleapis-mcp-toolbox

## The gap MCP Toolbox fills between an MCP client and a database

An MCP client such as Gemini CLI, Claude Code or Codex speaks the Model Context Protocol. A database speaks its own wire protocol. MCP Toolbox for Databases is the process in the middle: an open source MCP server, written in Go, that the README describes as connecting "your AI agents, IDEs, and applications directly to your enterprise databases".

The intended audience is two different groups. The first is developers who want to ask questions of a database from inside an editor or CLI without building a server first. The second is teams shipping agents that need database calls in production, where a generic "run any SQL" tool is not acceptable. The README frames this as a dual purpose: a ready-to-use MCP server for build-time exploration, and a custom tools framework for run-time agents. Those two purposes have different risk profiles, and the project does not hide that.

## Prebuilt tools, custom toolsets, and where the SQL actually lives

The mechanism has three parts. A client starts the Toolbox process over stdio or HTTP. The Toolbox loads a set of tools, either from a prebuilt configuration selected on the command line or from a tools.yaml you write. Each tool maps to a statement or operation against a configured source, and the client sees it as an MCP tool it can call.

The prebuilt path is the shortcut. Running with a --prebuilt=<database> flag loads standard tools for that engine, and the README names list_tables and execute_sql as examples. A toolset can be narrowed with the --prebuilt=<database>/<toolset> syntax, for instance --prebuilt=postgres/data to load only SQL tools. That narrowing matters: the broader the toolset, the more surface the client can reach.

The custom path is where the project expects production work to happen. Instead of handing the model a general query tool, you define structured queries and semantic search in a configuration file, and the server exposes only those. The README lists Restricted Access, Structured Queries and Semantic Search as the safety mechanisms for this mode. The trade-off is obvious once stated: prebuilt tools are fast to set up and broad in reach, custom tools are slower to set up and narrow by construction. Nothing in the README suggests the prebuilt tools carry per-user authorization logic.

The go.mod file shows how wide the connector surface is. It requires drivers and cloud client libraries for BigQuery, Spanner, Firestore, AlloyDB, Cloud SQL, Bigtable, ClickHouse, CockroachDB, Couchbase, Elasticsearch, Cassandra, MySQL, Oracle, and more. That is a large dependency tree for a single binary, and it explains why the Dockerfile builds with CGO enabled.

## Installing MCP Toolbox and connecting a Postgres database

The README's quick start for prebuilt tools does not ask you to install a binary at all. It adds an entry to the MCP client configuration file, usually mcp.json or claude_desktop_config.json, and runs the server through npx. The README gives this example for PostgreSQL:

```json
{
  "mcpServers": {
    "toolbox-postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@toolbox-sdk/server",
        "--prebuilt=postgres",
        "--stdio"
      ]
    }
  }
}
```

After editing that file, restart the client. The README states that you then set the appropriate environment variables to connect, and points to the Prebuilt Tools Reference for the per-database list. Those variable names are not in the README, so read the reference page for your engine before expecting a successful connection.

If you would rather run the server yourself, the repository ships a Dockerfile. It is a multi-stage build that compiles with CGO and Zig for cross-compilation, then copies the binary into gcr.io/distroless/cc-debian12:nonroot and runs it as the nonroot user. The README also mentions binaries and other execution methods under Install & Run the Toolbox server. The image is the more reproducible route; the npx route is the faster one for a single developer.

There is also a repository rename to be aware of. The README states that genai-toolbox was renamed to mcp-toolbox, and gives the command to update an existing remote:

```bash
git remote set-url origin https://github.com/googleapis/mcp-toolbox.git
```

If you cloned the project under its old name, that is the one-line fix. Documentation and blog posts written before the rename still use the old name, which is worth remembering when you search for configuration examples.

## The prebuilt tools are exploration tools, not an authorization layer

The most important limitation is conceptual rather than technical. A prebuilt toolset for PostgreSQL includes a generic SQL execution tool. Any client connected with that toolset can run statements the database account permits. MCP Toolbox does not sit between the statement and the database to decide whether it is allowed; the database does that, using the credentials you gave the server.

The README's security story is about the custom tools framework, where you define the statements yourself. If you deploy the prebuilt configuration against a production database and connect an agent to it, the agent's reach is the reach of the database user. That is a real deployment decision, and the documentation does not present the prebuilt mode as a hardened production configuration.

A second limitation is client-side. The README describes Toolbox as usable from "any MCP-compatible IDE or client", and lists Gemini CLI, Google Antigravity, Claude Code and Codex. Whether a given client supports stdio, HTTP, or both is a property of that client, not of Toolbox, and the README does not enumerate the matrix. If your client only speaks one transport, check before planning the deployment.

Finally, the dependency surface is broad. Supporting this many engines in one binary means the build pulls in a long list of drivers and cloud SDKs, visible in go.mod. That is a maintenance cost for the project and a larger artifact for you, though it also means one server covers engines that would otherwise need separate integrations.

## How MCP Toolbox compares with writing your own MCP server

The direct alternative is a small MCP server you write yourself. If your agent needs exactly three database operations, a hand-written server in the language of your choice can expose exactly those three tools and nothing else. You control the transport, the authentication, and the error messages. The cost is that you also own the connection pooling, the retry behaviour, and every future tool you add.

MCP Toolbox takes the opposite position. It ships connection pooling, integrated authentication including IAM for Google Cloud databases, and OpenTelemetry-based metrics and tracing, according to the README. In exchange you accept its configuration format, its release cadence, and a binary that carries drivers for engines you do not use.

The honest dividing line is how many engines and how many tools you need. One database and three tools: a hand-written server is smaller and easier to audit. Several engines, or a tool surface that will keep growing, or a requirement for tracing that you would otherwise have to build: the framework earns its keep. The repository also ships SDKs for Python, JavaScript and TypeScript, Go, and Java, so an application can call the tools without going through an MCP client at all, which is a different integration path from the IDE use case.

## Versioning, licence, and what an upgrade actually costs

The project uses Apache-2.0. That permits commercial use and modification, and it includes a patent grant. It does not give you any warranty, and it does not oblige the maintainers to support your deployment. If you fork the server or ship it inside a product, the licence conditions around notices and attribution still apply; that is a question for your own counsel, not something a review can settle.

The repository keeps an UPGRADING.md and a CHANGELOG.md at the top level, which is a signal that breaking changes are expected to be documented rather than discovered. Releases in the recent series land roughly every two to three weeks: v1.8.0 on 2026-07-28, v1.9.0 on 2026-08-14, v1.10.0 on 2026-08-27. The last push to the repository was on 2026-09-09. A cadence like that is good for fixes and bad for anyone who pins a version and forgets it.

The upgrade cost is not the binary, it is the tool definitions. If you maintain a tools.yaml with structured queries, a change to the configuration schema or to a source's parameters is the thing that breaks your deployment. Read UPGRADING.md before moving between minor versions, not after. Teams that only use the prebuilt tools have a much smaller upgrade surface, since there is no configuration of their own to migrate.

## Conclusion

Adopt MCP Toolbox if you want an MCP-compatible client talking to a database without writing a server, and you accept that the prebuilt tools are generic exploration tools rather than a permission model. Do not adopt it as a substitute for database-side access control, and do not expect the prebuilt tools to enforce row-level rules for you. Before rolling it out, verify two things: which toolsets the prebuilt config for your database actually loads, and whether your client can use stdio or needs the HTTP transport. Start from the prebuilt configuration page for your engine, then replace the generic tools with a tools.yaml that names only the statements you are willing to run.

## FAQ

### What is MCP Toolbox for Databases?

It is an open source Model Context Protocol server, written in Go and published under Apache-2.0, that connects AI agents, IDEs and applications to databases. It can run with prebuilt generic tools for a given engine or with custom tools you define in configuration.

### How do I install MCP Toolbox?

The README's quick start adds an entry to your MCP client configuration file, usually mcp.json or claude_desktop_config.json, and starts the server through npx with the @toolbox-sdk/server package. The repository also ships a Dockerfile and the README mentions binaries and other execution methods.

### Can I use MCP Toolbox in VS Code?

The README says the Toolbox works with any MCP-compatible IDE or client and names Gemini CLI, Google Antigravity, Claude Code and Codex as examples. It does not list VS Code explicitly, so check whether your client supports the stdio or HTTP transport the server is started with.

### What is the difference between MCP Toolbox and an MCP server?

MCP Toolbox is itself an MCP server. The distinction the README draws is between its prebuilt generic tools, which are meant for build-time exploration, and its custom tools framework, where you define structured queries and semantic search for production agents.

### Which databases does MCP Toolbox support?

The README lists AlloyDB, BigQuery, Cloud SQL, Spanner, Firestore and Knowledge Catalog on Google Cloud, plus PostgreSQL, MySQL, MariaDB, SQL Server, Oracle, MongoDB, Redis, Elasticsearch, CockroachDB, ClickHouse, Couchbase, Neo4j, Snowflake and Trino among others.

## Sources

- [googleapis/mcp-toolbox on GitHub](https://github.com/googleapis/mcp-toolbox)
- [License: Apache-2.0](https://github.com/googleapis/mcp-toolbox/blob/main/LICENSE)
- [Project website](https://mcp-toolbox.dev/documentation/introduction/)
- [README](https://github.com/googleapis/mcp-toolbox/blob/main/README.md)
- [Releases](https://github.com/googleapis/mcp-toolbox/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/googleapis-mcp-toolbox