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=` 啟動既有工具，快速讓相容的 IDE 或 CLI 探索 schema、列出資料表、執行受控資料庫操作。
2. **自訂工具框架**：在 `tools.yaml` 中明確定義資料來源、工具參數與 SQL，將領域邏輯包裝成固定介面，供 production Agent 使用。
這個分層很重要。預建工具適合快速驗證與開發期探索；自訂工具則把工具的名稱、描述、參數與查詢邏輯從模型提示中抽離，讓它們可以被 code review、測試與版本控制。
## 架構：Source、Tool、Toolset 與 Prompt
MCP Toolbox 的設定不是一份塞滿任意 SQL 的 prompt，而是由幾種明確資源組合而成。
### Source：資料連線邊界
`source` 描述 Toolbox 可以連到哪個資料來源，例如 PostgreSQL：
```yaml
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 工具：
```yaml
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` 是一組可以一起載入的工具：
```yaml
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：
```json
{
"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 載入設定：
```bash
./toolbox --config tools.yaml
```
或使用官方提供的便利方式：
```bash
npx @toolbox-sdk/server --config tools.yaml
```
以訂房服務為例，可以把查詢與寫入工具分開，並讓 Agent 只拿到它需要的 toolset：
```yaml
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 的最小呼叫形態如下：
```python
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 流程。
設定概念如下：
```yaml
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：
- 官方文件：
- 官方 Generic OIDC Auth 文件：
- 官方 MCP Authorization 文件：
- 官方 Python Core SDK 文件：