AI-Chain
資料庫 Agent MCP Toolbox for Databases MCP SQL

MCP Toolbox for Databases：讓 Agent 安全連接企業資料庫的開源工具鏈

MCP Toolbox for Databases 將資料庫能力包成可審查的 MCP 工具，從預建整合、tools.yaml、自訂 toolset 到 OIDC 授權與 OpenTelemetry，建立 Agent 連接企業資料的工程邊界。本文拆解它的架構、上手方式、安全取捨與 production 導入檢查表。

分享:
MCP Toolbox for Databases：讓 Agent 安全連接企業資料庫的開源工具鏈

MCP Toolbox for Databases：讓 Agent 安全連接企業資料庫的開源工具鏈

當 Agent 開始接觸企業資料，真正困難的通常不是再接一個模型，而是把資料庫存取變成可控、可觀測、可維護的工具介面。直接讓模型產生任意 SQL，容易遇到權限過大、查詢不可預期、連線生命週期混亂，以及出了問題卻沒有追蹤資料等工程風險。

Google 開源的 MCP Toolbox for Databases，正好把問題放在資料庫工具層處理。它是一個 Model Context Protocol（MCP）伺服器，也是一套自訂工具框架：一方面提供可直接連接資料庫的預建工具，另一方面讓團隊用 tools.yaml 定義來源、參數化查詢、工具集合與提示詞，再讓 Gemini CLI、Claude Code、Codex、Agent Development Kit（ADK）、LangChain、LlamaIndex 或自建 Agent 使用。

本文不把它包裝成「讓模型自動管理資料庫」的魔法，而是從原始碼、官方文件與可執行設定拆解它的實際定位：如何把資料庫能力包成 MCP 工具、怎麼限制 Agent 能做的事、什麼情況適合採用，以及上線前仍要自己補上的治理措施。

本文資料查證時間：2026 年 9 月 3 日。GitHub 專案當時約有 16,303 顆 stars，最新 release 為 v1.10.0，採 Apache-2.0 授權。版本與 stars 會持續變動，請以官方頁面為準。

先講結論：它不是 ORM，而是 Agent 與資料庫之間的工具層

MCP Toolbox 的核心價值不是替代 PostgreSQL、BigQuery 或 MongoDB，也不是另一個 ORM。它位在 Agent 與資料來源中間，負責把「資料庫能做什麼」整理成 Agent 可以發現、載入與呼叫的工具。

官方設計同時支援兩種使用方式：

  1. 預建 MCP Server：用 --prebuilt=<database> 啟動既有工具，快速讓相容的 IDE 或 CLI 探索 schema、列出資料表、執行受控資料庫操作。
  2. 自訂工具框架：在 tools.yaml 中明確定義資料來源、工具參數與 SQL，將領域邏輯包裝成固定介面，供 production Agent 使用。

這個分層很重要。預建工具適合快速驗證與開發期探索；自訂工具則把工具的名稱、描述、參數與查詢邏輯從模型提示中抽離，讓它們可以被 code review、測試與版本控制。

架構：Source、Tool、Toolset 與 Prompt

MCP Toolbox 的設定不是一份塞滿任意 SQL 的 prompt，而是由幾種明確資源組合而成。

Source：資料連線邊界

source 描述 Toolbox 可以連到哪個資料來源，例如 PostgreSQL：

kind: source
name: analytics-db
type: postgres
host: ${DB_HOST}
port: 5432
database: ${DB_NAME}
user: ${DB_USER}
password: ${DB_PASSWORD}

官方文件支援多種 Google Cloud 與第三方資料庫，包括 AlloyDB、BigQuery、Cloud SQL、Spanner、Firestore、PostgreSQL、MySQL、MariaDB、SQL Server、Oracle、MongoDB、Redis、Elasticsearch、CockroachDB、ClickHouse、Couchbase、Neo4j、Snowflake 與 Trino 等。實際可用的整合與工具，以官方 Prebuilt Tools Reference 為準。

這一層的實務重點是不要把密碼直接寫入設定檔。官方 quickstart 建議使用 ${ENV_NAME} 形式的環境變數替換；production 則應再搭配 Secret Manager、短期憑證與資料庫本身的最小權限帳號。

Tool：把動作變成固定介面

tool 定義 Agent 可以採取的單一動作。下面是一個只查詢飯店名稱的參數化 SQL 工具：

kind: tool
name: search-hotels-by-name
type: postgres-sql
source: analytics-db
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 || '%';

模型看到的不是「請自由發揮 SQL」，而是工具名稱、用途、參數與結果。這不等於自動完成安全審查，但它提供了一個更容易審查的控制面：團隊可以限制欄位、固定 WHERE 條件、加入分頁，並為寫入操作建立獨立工具。

讀取工具與寫入工具最好分開設計。像 search-hotels-by-name 可以使用只讀帳號；book-hotel 或 update-hotel 則應有明確的業務規則、權限、審批或交易邊界。不要因為 MCP 讓呼叫變簡單，就把資料庫的寫入權限全部交給 Agent。

Toolset：控制工具曝光範圍

toolset 是一組可以一起載入的工具：

kind: toolset
name: booking-read-tools
tools:
  - search-hotels-by-name
  - search-hotels-by-location

當不同 Agent 或應用程式需要不同能力時，toolset 比「把整個資料庫的所有工具一次暴露出去」更合理。例如客服 Agent 只需要查詢訂單，分析 Agent 才需要聚合報表，內部開發工具才可能需要 schema 探索。工具集合也能協助降低模型上下文與錯誤選擇的成本。

Prompt：把可重用指引放進設定

Toolbox 也能在設定中定義 prompts，例如程式碼審查或資料分析的固定指引。這些 prompt 可以引用參數，讓同一套 Agent 工具在不同呼叫情境中保持一致。不過 prompt 不是權限系統；敏感資料保護與工具授權仍應由 auth service、資料庫帳號與應用層共同負責。

兩種啟動路徑：快速試用與正式部署

用預建工具快速驗證

對想先確認「MCP client 能否看見資料庫工具」的團隊，官方 README 提供 npx 啟動方式。以下設定把 PostgreSQL 預建工具接到 MCP client：

{
  "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": "readonly_user",
        "POSTGRES_PASSWORD": "${POSTGRES_PASSWORD}"
      }
    }
  }
}

--prebuilt=postgres 會載入 PostgreSQL 的預建工具，也可以用 --prebuilt=postgres/data 只載入特定 toolset。支援的資料庫與工具名稱會隨版本變動，因此正式使用前應查閱 release 對應的 reference，而不是把 README 範例當成永久 API 契約。

官方也提醒，npx 方式偏向方便，不一定是最適合 production 的執行方式。正式部署可採官方 binary 或 container image，並固定版本，不要無條件使用 latest。

用 tools.yaml 建立領域工具

自訂工具的流程是：先建立 source，再建立 tool，最後用 Toolbox server 載入設定：

./toolbox --config tools.yaml

或使用官方提供的便利方式：

npx @toolbox-sdk/server --config tools.yaml

以訂房服務為例，可以把查詢與寫入工具分開，並讓 Agent 只拿到它需要的 toolset：

kind: source
name: booking-db
type: postgres
host: ${BOOKING_DB_HOST}
port: 5432
database: ${BOOKING_DB_NAME}
user: ${BOOKING_DB_USER}
password: ${BOOKING_DB_PASSWORD}
---
kind: tool
name: find-booking
type: postgres-sql
source: booking-db
description: Find a booking by its public confirmation code.
parameters:
  - name: confirmation_code
    type: string
    description: Public booking confirmation code.
statement: >-
  SELECT id, status, checkin_date, checkout_date
  FROM bookings
  WHERE confirmation_code = $1
  LIMIT 1;
---
kind: toolset
name: customer-support
tools:
  - find-booking

這種設計的重點不是 YAML 本身，而是把工具契約放在可審查的設定中：資料源名稱、SQL、輸入型別、描述與暴露範圍都能進 Git。團隊仍需要加入 SQL migration、整合測試、查詢 timeout、結果筆數上限與敏感欄位遮罩，因為 Toolbox 不會替你完成所有資料治理。

與 Agent 應用整合：MCP 或 SDK

如果使用現成 MCP client，Toolbox 可以作為獨立 MCP server。若你正在寫自己的 Agent 應用，官方也提供 SDK：

  • Python：toolbox-core，另有 ADK、LangChain、LlamaIndex 整合。
  • JavaScript／TypeScript：@toolbox-sdk/core 與相應框架整合。
  • Go：官方 Go SDK 與 ADK、Genkit、LangChain 等 quickstart。
  • Java：官方 Java SDK。

Python core SDK 的最小呼叫形態如下：

import asyncio
from toolbox_core import ToolboxClient

async def main():
    async with ToolboxClient("http://127.0.0.1:5000") as toolbox:
        tool = await toolbox.load_tool("find-booking")
        result = await tool(confirmation_code="ABC123")
        print(result)

if __name__ == "__main__":
    asyncio.run(main())

SDK 預設以非同步 client 載入與呼叫工具，並支援透過 context manager 管理 HTTP session。若不使用 async with，就必須在 finally 中顯式 close()。這是很容易被忽略、但會直接影響長時間服務穩定性的細節。

SDK 也支援 MCP over HTTP 的多個協定版本與協商。需要互通舊 client 時，可以明確指定 protocol；需要嚴格鎖定版本時，則應傳入只含單一版本的清單。這讓升級可以被測試，而不是把協定變更留給 production 才發現。

安全設計：有能力不代表應該開放能力

官方文件把安全分成幾個可配置層次，這是 MCP Toolbox 比簡單「資料庫問答 prompt」更有工程價值的地方。

Generic OIDC 與 MCP Authorization

Generic Auth Service 可以整合符合 OIDC 的 identity provider。Toolbox 能透過 discovery 或指定的 authorizationServer 取得 JWKS，檢查 JWT 的簽章、過期時間、audience 與 scopes。當 mcpEnabled: true 時，則能在 MCP endpoint 上驗證標準 Authorization: Bearer token，也能處理 opaque token 的 introspection 流程。

設定概念如下：

kind: authService
name: company-oidc
type: generic
audience: ${MCP_AUDIENCE}
authorizationServer: https://idp.example.com
mcpEnabled: true
scopesRequired:
  - mcp:tools

官方 MCP auth 文件指出，啟用後會自動提供 Protected Resource Metadata endpoint，部署時還需要設定絕對的 TOOLBOX_URL，讓 client 知道受保護資源的實際位置。若部署在 Cloud Run，也要注意 Cloud Run IAM token 與 Toolbox 的 MCP bearer token 可能使用不同授權層，不能混為一談。

Tool-level 授權與參數注入

除了保護整個 MCP server，auth service 也能用在工具的 authRequired、scopesRequired，或把 token claim 注入參數。這讓工具可以做到「同一個 server，不同工具需要不同 scope」，避免所有呼叫只靠一個粗粒度的全域權限。

但設定授權並不會消除 prompt injection、資料外洩與錯誤工具選擇。官方 security 文件明確把 prompt injection、jailbreak 與敏感資料外洩列為需要處理的風險；落地時仍應加入：

  • 對讀取與寫入工具使用不同資料庫角色。
  • 為寫入與高成本查詢設計人工確認或業務審批。
  • 對 SQL、結果筆數、timeout 與 rate limit 做獨立監控。
  • 對敏感欄位做 view、遮罩或欄位級權限，不要只依賴模型不去問。
  • 不把完整資料庫 schema 無差別暴露給每一個 Agent。

可觀測性與部署：從本機 demo 走向服務

MCP Toolbox 的 README 將 connection pooling、整合式 auth，以及 OpenTelemetry metrics 與 tracing 列為內建能力。這些能力的價值在於：當 Agent 回答變慢或工具結果錯誤時，團隊可以把一次模型工作流追到 MCP 呼叫、工具執行與資料庫查詢，而不是只看到聊天介面上的一句錯誤訊息。

官方提供 binary、container image 與 Docker Compose 的部署路徑。Docker Compose 範例以 Toolbox 加 PostgreSQL 為主，服務通常在 5000 port 提供介面；正式環境建議：

  1. Pin Toolbox 與資料庫 image 版本，不要使用浮動的 latest。
  2. 將 tools.yaml 與 secrets 分離，透過 secret mount 或 Secret Manager 注入。
  3. 只在內網或受控網段暴露資料庫連線，MCP endpoint 前置 TLS、identity 與 rate limiting。
  4. 設定 health check、timeout、connection pool 上限與 graceful shutdown。
  5. 讓 OpenTelemetry trace 包含 client、tool、database 等可關聯欄位，但避免把 token 或敏感結果寫進 span。

要特別注意，工具層的 observability 只能告訴你發生了什麼；它不會自動替你判斷某個查詢是否商業上合理。資料品質、成本控制與業務授權仍是應用團隊的責任。

它適合誰，又不適合誰？

適合的情境

  • 團隊已經採用 MCP client，希望把多種資料庫能力用統一方式接進 IDE 或 Agent。
  • 需要把自然語言操作限制在一組固定、可 code review 的工具。
  • 同一份資料庫工具要被 ADK、LangChain、LlamaIndex 或多個自建應用重用。
  • 需要 OIDC、scope、OpenTelemetry、connection pooling 等服務級能力。
  • 想先用預建工具做探索，再逐步把高風險操作收斂成自訂 toolset。

不適合直接採用的情境

  • 只是做一次性離線分析，直接用既有資料管線更簡單。
  • 團隊沒有能力管理資料庫權限、秘密、網路與可觀測性，卻打算把 production database 直接暴露給 Agent。
  • 需求是複雜交易流程、嚴格一致性或大量批次處理；這些邏輯更適合放在傳統服務或 workflow engine，再把少量安全動作包成工具。
  • 只想要一個任意 SQL 生成器。Toolbox 的價值恰恰在於把任意能力收斂成可審查工具，不是放大任意 SQL。

導入檢查表

在把 MCP Toolbox 接進 production 前，可以用下面的順序降低風險：

  • [ ] 先選一個 read-only、低敏感度資料來源做試點。
  • [ ] 先使用一個最小 toolset，不要一次載入整個資料庫。
  • [ ] 所有 credentials 改用環境變數或 secrets，設定檔不放明文密碼。
  • [ ] 每個 tool 都有明確描述、輸入型別、結果上限與 timeout。
  • [ ] 讀取、寫入、管理功能使用不同資料庫角色與不同 scope。
  • [ ] 高風險 tool 有人工確認、idempotency 與 audit log。
  • [ ] 測試 MCP 協定版本、SDK session close 與網路重試行為。
  • [ ] Pin binary／container 版本，並建立升級前的相容性測試。
  • [ ] 驗證 trace、metrics 與 log 不會洩漏 token、密碼或敏感資料。
  • [ ] 對模型可能被 prompt injection 誘導的情境做紅隊測試。

結語

MCP Toolbox for Databases 值得關注的地方，不只是「可以讓 Agent 查資料庫」，而是它把資料庫能力拆成 source、tool、toolset、auth 與 SDK 等可組合的工程元件。這讓 MCP 不再只是把一堆 function 丟給模型，而可以成為一個有邊界、有版本、有授權與可觀測性的工具層。

它最實際的導入路徑，是先用預建工具驗證整合，再用 tools.yaml 把高價值查詢收斂成固定工具，最後補上資料庫最小權限、MCP authorization、審批與 observability。若團隊願意把這些治理工作一起完成，Toolbox 能縮短 Agent 連接企業資料的距離；如果只把它當成任意 SQL 的捷徑，MCP 只會把既有資料安全問題更快地暴露出來。

參考資料

  • GitHub：<https://github.com/googleapis/mcp-toolbox>
  • 官方文件：<https://mcp-toolbox.dev/>
  • MCP Authorization：<https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization>
  • 官方 Generic OIDC Auth 文件：<https://github.com/googleapis/mcp-toolbox/blob/main/docs/en/documentation/configuration/authentication/generic.md>
  • 官方 MCP Authorization 文件：<https://github.com/googleapis/mcp-toolbox/blob/main/docs/en/documentation/configuration/toolbox_mcp_auth.md>
  • 官方 Python Core SDK 文件：<https://github.com/googleapis/mcp-toolbox/blob/main/docs/en/documentation/connect-to/toolbox-sdks/python-sdk/core/index.md>