别给 Agent 一把万能 SQL：MCP Toolbox 把预置探库和生产工具拆开

源微信页常见验证码拦截。正文以官方仓 googleapis/mcp-toolbox（Apache-2.0，约 1.6 万 Star，旧名 genai-toolbox）、文档站 mcp-toolbox.dev 与 v1.9.0（2026-08-14）发行说明为准，不沿用源标题的口号句式，也不把「预置 execute_sql」写成生产级权限模型。

给 Agent 接数据库，最容易走偏的一步是：MCP 里塞一个「随便执行 SQL」的工具，再把应用账号密码写进配置。IDE 里探表、看执行计划、查锁，这套够用；一旦同一套工具挂到面向用户的生产 Agent 上，模型一次幻觉就能 DROP、改价格、扫敏感列。Google 这套 Toolbox 的价值不在「又能连 Postgres」，而在把探库和生产查库拆成两套用法：构建期用预置通用工具；运行期用 tools.yaml 把语句钉死、把连接池和观测留在控制面。

一、Agent 查库真正缺的是控制面，不是又一个驱动

自己写一个数据库 MCP，通常三件事：读连接串、把模型给出的 SQL 丢进驱动、把结果切成文本返回。这在 Demo 里很快。痛点出现在第二周：连接什么时候建、什么时候还？超时、事务、只读会话谁保证？工具描述改了要不要重启 Agent？BigQuery IAM 和本地 Postgres 密码怎么统一？多 Agent 共用同一套查询，配置散落在每个编排框架里。

MCP Toolbox 的定位是插在编排层和数据库之间的控制面。官方说法是：集中存放、分发、调用工具，更新工具时不必一定重部署应用。它不是又一个 ORM，也不是 NL2SQL 模型；模型仍然负责选工具、填参数，Toolbox 负责连接、鉴权、参数绑定和观测。

仓库经历过一次命名对齐。项目最初叫 Gen AI Toolbox for Databases（googleapis/genai-toolbox），当时 MCP 还没成为事实标准；兼容 MCP 后正式改名为 MCP Toolbox for Databases，远程应切到 https://github.com/googleapis/mcp-toolbox.git。文档站仍同时提到旧名，搜索时别当成两个产品。

Prebuilt configs are intended for ‘build-time’ use cases, where agents are helping trusted developers build things. They are not secure enough for ‘run time’ use cases.

这句话是全文的选型锚。预置工具面向受信任的开发者在 IDE / CLI 里探库；生产 Agent 面向可能不可信的用户输入，必须换成自定义参数化工具，再叠数据库账号权限。把 execute_sql 直接挂到客服 Bot，等于把超级用户交给下一个 Prompt 注入。

二、两套入口：构建期预置探索，运行期自定义工具

Toolbox 公开的双用途，对应两套完全不同的风险模型。

构建期（Ready-to-use MCP Server）：一条 --prebuilt=postgres（或 alloyDB、BigQuery、Spanner 等）立刻拿到通用工具。Postgres 预置配置目前包括 list_tables、list_schemas、list_views、get_query_plan、list_locks、database_overview 以及动态的 execute_sql 等。用途是：在 Cursor、Claude Code、Gemini CLI、Codex、Antigravity 里用自然语言问「有哪些表」「这条查询怎么走索引」。官方还提供 Google Antigravity MCP Store 的一键安装，以及 Gemini CLI 扩展（例如 Cloud SQL Postgres、通用 mcp-toolbox 扩展）。

运行期（Custom Tools Framework）：自己写 tools.yaml，每条工具绑定固定 statement 和类型化 parameters。模型只能填 $1、$2，不能改 SQL 骨架。这里才允许把「按酒店名搜索」「按 ID 预订」交给面向用户的 Agent。文档明确：可用参数化查询、语义检索、受控的 NL2SQL；安全来自受限访问 + 结构化语句，而不是正则屏蔽关键字。

客户端接入也分三条路，不要混用文档代差：

Google Cloud 另有托管 MCP Servers。自托管 Toolbox 适合要自定义语句、混合多数据源、或数据不能出内网；托管方案适合只要官方预置工具、不想运维二进制。文档 FAQ 专门对比二者，选型时别把「开源控制面」和「托管端点」写成同一个东西。

三、预置探库：环境变量进 MCP，不要把密码写进仓库

Postgres 预置值是 --prebuilt=postgres。必填环境变量是 POSTGRES_DATABASE、POSTGRES_USER、POSTGRES_PASSWORD；POSTGRES_HOST / POSTGRES_PORT 可选，另有 POSTGRES_QUERY_PARAMS 往连接串追加查询参数。数据库侧权限按工具需要授予：只探库就 SELECT，不要给应用 Owner。

Cursor / Claude 一类客户端，最小配置可以写成：

{
  "mcpServers": {
    "toolbox-postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@toolbox-sdk/server",
        "--prebuilt=postgres",
        "--stdio"
      ],
      "env": {
        "POSTGRES_HOST": "127.0.0.1",
        "POSTGRES_PORT": "5432",
        "POSTGRES_DATABASE": "toolbox_db",
        "POSTGRES_USER": "toolbox_user",
        "POSTGRES_PASSWORD": "my-password"
      }
    }
  }
}

npx 路径图方便，官方注明偏便利、不偏性能；长期挂在 IDE 里更建议发行版二进制或容器。二进制同样走 stdio：

{
  "mcpServers": {
    "bigquery": {
      "command": "./toolbox",
      "args": ["--prebuilt", "bigquery", "--stdio"],
      "env": {
        "BIGQUERY_PROJECT": "PROJECT_ID"
      }
    }
  }
}

预置配置可以过滤工具集，例如 --prebuilt=postgres/data 只加载 SQL 类工具，避免把复制槽、autovacuum、角色列表一并暴露给编码助手。也可以把 --prebuilt 和 --config tools.yaml 叠在一起：左边保留探库，右边加上你钉死的业务工具。

Google Cloud 侧预置覆盖 AlloyDB、BigQuery、Cloud SQL（Postgres / MySQL / SQL Server）、Spanner、Firestore、Knowledge Catalog（原 Dataplex），以及部分 Admin API（建集群、建实例）。非 GCP 侧包括 PostgreSQL、MySQL、MariaDB、SQL Server、Oracle、MongoDB、Redis、Elasticsearch、CockroachDB、ClickHouse、Couchbase、Neo4j、Snowflake、Trino，以及 Looker、OceanBase、SingleStore、FalkorDB、MindsDB、Cloud Healthcare、Cloud Monitoring、Cloud Storage、Dataproc 等。完整工具名以 Prebuilt Configs 为准，版本之间预置工具会变，不要把旧博客里的两三个名字当成全集。

对动态 SQL 工具，官方写得很硬：MCP 的确认弹窗和 tool annotations 不是安全边界。不要用关键字黑名单幻想「拦住了 DROP」。探库账号做成专用身份，exploratory Agent 通常只要指定 schema 的 SELECT；写迁移另开窗口、另开角色。

四、自定义工具：tools.yaml 把语句钉死

配置主文件是 tools.yaml。v0.26 之后文档默认 flat 格式：每个资源一块 kind:，用 --- 分隔。旧的嵌套 sources: / tools: 映射仍能在历史版本文档里看到，新项目不要混写。密钥用 ${ENV_NAME}，可带默认值 ${DB_PORT:3306}，禁止把密码写进仓库。

官方 Quickstart 用酒店表演示运行期工具。先准备最小权限用户和样例表，再声明数据源、工具和工具集：

kind: source
name: my-pg-source
type: postgres
host: 127.0.0.1
port: 5432
database: toolbox_db
user: ${POSTGRES_USER}
password: ${POSTGRES_PASSWORD}
---
kind: tool
name: search-hotels-by-name
type: postgres-sql
source: my-pg-source
description: Search for hotels based on name.
parameters:
  - name: name
    type: string
    description: The name of the hotel.
statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%';
---
kind: tool
name: book-hotel
type: postgres-sql
source: my-pg-source
description: Book a hotel by its ID.
parameters:
  - name: hotel_id
    type: string
    description: The ID of the hotel to book.
statement: UPDATE hotels SET booked = B'1' WHERE id = $1;
---
kind: toolset
name: my-toolset
tools:
  - search-hotels-by-name
  - book-hotel

要点不是 YAML 语法，而是语句骨架不可被模型改写。Postgres 占位符是 $1、$2，MySQL 是 ?。把用户输入拼进字符串再执行，等于自己把 SQL 注入重新打开。book-hotel 这种写工具只应出现在明确需要副作用的工具集里；面向只读问答的 Agent，工具集里根本不要放 UPDATE。

同一份配置还可以声明：

• toolset：按 Agent 分组加载，客服 Bot 和 DBA 助手不要共用一个集合
• group：把 tools / prompts / resources / resourceTemplates 收进一个带描述的作用域（toolset 是只含工具的 group）
• prompt：给客户端的结构化提示模板
• resource / resourceTemplate：只读文档、DDL、日志路径；ui: true 可走 MCP Apps，让客户端渲染交互界面

服务默认开启配置热加载，改 YAML 不必重启；要冻结用 --disable-reload。--ui 会打开交互界面，方便测授权参数和工具集，适合本地，不适合把 UI 暴露到公网。

已启动的服务器给 MCP 客户端时：

{
  "mcpServers": {
    "toolbox": {
      "type": "http",
      "url": "http://127.0.0.1:5000/mcp"
    }
  }
}

只暴露一个工具集时，把 URL 换成 http://127.0.0.1:5000/mcp/my-toolset。本地验收可用 MCP Inspector：npx @modelcontextprotocol/inspector，Transport 选 Streamable HTTP，地址 http://127.0.0.1:5000/mcp。

五、安装路径：二进制、容器、Homebrew、npx

以 GitHub Releases 的 v1.9.0（2026-08-14）为例。文档个别页面会出现 1.10 / 1.11 占位，落地前以 Releases 为准。

Linux amd64 二进制：

export VERSION=1.9.0
curl -L -o toolbox \
  https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
./toolbox --config tools.yaml

macOS Apple Silicon 把路径换成 darwin/arm64；Intel 用 darwin/amd64；Windows 下载 toolbox.exe。容器：

export VERSION=1.9.0
docker pull us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:$VERSION
docker run -p 5000:5000 \
  -v "$(pwd)/tools.yaml:/app/tools.yaml" \
  us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:$VERSION \
  --config /app/tools.yaml

Homebrew：brew install mcp-toolbox，然后 toolbox --config tools.yaml。源码安装需要较新的 Go：go install github.com/googleapis/mcp-toolbox@v1.9.0。npx @toolbox-sdk/server --config tools.yaml 适合试配，不适合当生产进程。

Gemini CLI 可以不手写 mcp.json：

npm install -g @google/gemini-cli
gemini extensions install https://github.com/gemini-cli-extensions/mcp-toolbox
gemini

/mcp list 确认服务器；Cloud SQL / BigQuery 另有专用扩展。toolbox help 列出全部 flag。停止用进程终止信号即可。

Python 应用侧加载工具（服务已在 127.0.0.1:5000）：

from toolbox_core import ToolboxClient

async with ToolboxClient("http://127.0.0.1:5000") as client:
    tools = await client.load_toolset("my-toolset")

pip install toolbox-core。LangChain / LlamaIndex / Genkit 有包装包，避免自己把 callable 转成各框架的 Tool 对象。Go SDK 在 github.com/googleapis/mcp-toolbox-sdk-go，Java 在 Maven com.google.cloud.mcp:mcp-toolbox-sdk-java。官方强调「不到 10 行接到 ADK / LangChain」——前提是 Toolbox 进程已经起来，SDK 并不内嵌数据库驱动。

六、防御纵深：参数绑定只是第一层

只靠 YAML 里的 $1 不够。文档把只读做成多层，生产至少叠三道：

1. 语句层：自定义工具只用参数化查询，禁止拼接。动态 execute_sql 留给受信任探库，不要进生产工具集。

2. 源层：部分 source 支持 readOnly: true，或在预置服务器用环境变量打开只读会话。这是协议级边界，工具配错也发不出写操作（以引擎是否支持为准）。

3. 账号层：Toolbox 使用的数据库角色本身只有该有的权限。这是最有效的一层——工具被提示词劫持，数据库仍会拒绝 DELETE。

此外还有 AuthServices（把终端用户身份传进查询）、MCP Authorization、以及针对注入 / 越狱 / 敏感字段泄漏的加固指南。连接池、GCP IAM、OpenTelemetry 指标和追踪是控制面自带能力，不必在每个 Agent 里重写一遍。

排坑清单（按出现频率）：

• 把预置工具当生产 API：官方已标明 build-time，不是 runtime
• 应用 Owner 账号给 MCP：探库和写库必须拆角色
• 密钥进 YAML：用 ${POSTGRES_PASSWORD}，配置进环境或密钥管理
• npx 当长期进程：改用二进制或容器
• 热加载当变更管理：生产建议 --disable-reload，改配走发布流程
• 一个 toolset 打天下：只读问答、下单、DBA 诊断分成三个集合
• Inspector 端口搞混：Toolbox 是 5000/mcp，Inspector 代理是 6277/6274
• 旧仓名克隆失败：genai-toolbox 已重命名，remote 改 mcp-toolbox
• flat / nested YAML 混用：新文档默认 flat kind: 块

本地没有现成库时，可先用 Docker 起 Postgres，再跑配套 practice/tools.yaml。不要把示例密码带进真实环境。

七、和「自己写 MCP」差在哪

它解决不了的问题也说清楚：它不替你生成正确的业务 SQL，不替代数据权限系统，也不能让不可信用户安全地「随便问库」。NL2SQL 若出现，应落在受控工具或独立分析服务里，而不是把生成出来的字符串直接丢进预置 execute_sql。

源文标题容易写成「Google 开了个项目，Agent 就能玩数据库」。工程上更准确的句子是：探库用预置工具，生产用钉死的语句，权限留在数据库账号上。 Toolbox 只是把这三句话做成可部署的 MCP 服务器。版本以 Releases 为准，工具列表以当前文档为准，旧名 genai-toolbox 只作为检索别名保留。