這很重要
SQL 模型情境協定（MCP）伺服器目前處於預覽階段，本文件及引擎實作可能會有所變動。 雖然 Data API 建構器版本 1.7 仍在預覽階段，但你必須明確使用預發布版本（例如 1.7.83-rc），因為 MCP 功能尚未包含在標籤中 :latest 。
SQL MCP 伺服器向 AI 代理開放六種資料操作語言（DML）工具。 這些工具提供一個有型別的 CRUD 表面，用於資料庫操作——建立、讀取、更新與刪除記錄，以及執行儲存程序。 所有工具都遵守基於角色的存取控制（RBAC）、實體權限及您設定中定義的政策。
什麼是 DML 工具？
DML（資料操作語言）工具處理資料操作：建立、讀取、更新與刪除記錄，以及執行儲存程序。 與修改結構的 DDL（資料定義語言）不同，DML 僅在現有資料表和檢視中的資料平面上運作。
六項 DML 工具為：
-
describe_entities- 發現可用的實體與操作 -
create_record- 插入新列 -
read_records- 查詢資料表與檢視 -
update_record- 修改現有的列 -
delete_record- 移除行 -
execute_entity- 執行儲存程序
當 DML 工具在全球且為實體啟用時，SQL MCP 伺服器會透過 MCP 協定公開它們。 代理程式不會直接與你的資料庫架構互動——它們是透過 Data API 建構器的抽象層來運作。
工具
工具列表回應
當代理呼叫 list_tools時，SQL MCP 伺服器會回傳：
{
"tools": [
{ "name": "describe_entities" },
{ "name": "create_record" },
{ "name": "read_records" },
{ "name": "update_record" },
{ "name": "delete_record" },
{ "name": "execute_entity" }
]
}
描述_實體
回傳目前角色可使用的實體。 每個條目包含欄位名稱、資料型別、主鍵及允許的操作。 這個工具不會查詢資料庫。 相反地，它會讀取從你的設定檔建立的內存配置。
{
"entities": [
{
"name": "Products",
"description": "Product catalog with pricing and inventory",
"fields": [
{
"name": "ProductId",
"type": "int",
"isKey": true,
"description": "Unique product identifier"
},
{
"name": "ProductName",
"type": "string",
"description": "Display name of the product"
},
{
"name": "Price",
"type": "decimal",
"description": "Retail price in USD"
}
],
"operations": [
"read_records",
"update_record"
]
}
]
}
備註
任何 CRUD 與執行 DML 工具所使用的實體選項皆直接來自 describe_entities。 每個工具附帶的內部語意描述強化了這個兩步驟流程。
建立紀錄
在資料表中建立一列新資料。 需要對該實體建立目前角色的權限。 工具會驗證輸入是否符合實體結構，執行現場層級權限，套用建立政策，並回傳已建立的紀錄及其產生的值。
read_records
查詢資料表或視圖。 支援篩選、排序、分頁及欄位選擇。 該工具從結構化參數建立確定性 SQL，套用讀取權限與欄位投影，並強制執行列級安全政策。
結果 read_records 會透過 Data API 建構器的快取系統自動快取。 你可以全局或每個實體設定快取存活時間（TTL），以減少資料庫負載。
更新記錄
修改現有列。 需要主鍵和欄位才能更新。 工具會驗證主鍵的存在，強制執行更新權限與政策，且僅更新目前角色可修改的欄位。
刪除紀錄
移除一個現有的行。 需要主鍵。 該工具會驗證主鍵的存在，執行刪除權限與政策，並以交易支援執行安全刪除。
警告
某些生產情境會全域停用此工具，以廣泛限制模型。
執行實體
執行一個儲存程序。 支援輸入參數與輸出結果。 該工具會驗證輸入參數與程序簽章的關聯，強制執行權限，並安全地傳遞參數。
執行時配置
在你的 dab-config.json 運行時區段全域配置 DML 工具：
{
"runtime": {
"mcp": {
"enabled": true,
"path": "/mcp",
"dml-tools": {
"describe-entities": true,
"create-record": true,
"read-records": true,
"update-record": true,
"delete-record": true,
"execute-entity": true
}
}
}
}
使用 CLI
使用 Data API 建構工具 CLI 分別設定屬性：
dab configure --runtime.mcp.enabled true
dab configure --runtime.mcp.path "/mcp"
dab configure --runtime.mcp.dml-tools.describe-entities true
dab configure --runtime.mcp.dml-tools.create-record true
dab configure --runtime.mcp.dml-tools.read-records true
dab configure --runtime.mcp.dml-tools.update-record true
dab configure --runtime.mcp.dml-tools.delete-record true
dab configure --runtime.mcp.dml-tools.execute-entity true
停用這些工具
當你在執行時層級停用工具時，無論實體權限或角色設定如何，代理都不會看到它。 這個設定在需要嚴格操作邊界時非常有用。
常見場景
- 停用
delete-record以防止生產環境中資料遺失 - 將
create-record功能停用於唯讀報告端點 - 當未使用儲存程序時停用
execute-entity
當工具全域被停用時，該工具會從回應中隱藏 list_tools ，且無法被呼叫。
實體設定
除非你明確限制，實體會自動參與 MCP。 這個 dml-tools 屬性存在是為了讓你可以排除某個實體在 MCP 之外或縮小其能力範圍，但一般使用時不需要設定任何東西。
{
"entities": {
"Products": {
"mcp": {
"dml-tools": true
}
},
"SensitiveData": {
"mcp": {
"dml-tools": false
}
}
}
}
如果你沒有在實體上指定 mcp.dml-tools ，預設是 true 當 MCP 全域啟用時。
細粒度控制
你可以為個別實體停用特定工具：
{
"entities": {
"AuditLogs": {
"mcp": {
"dml-tools": {
"create-record": true,
"read-records": true,
"update-record": false,
"delete-record": false
}
}
}
}
}
此配置允許代理建立並讀取稽核日誌，但防止修改或刪除。
RBAC 整合
每個 DML 工具操作都會強制執行基於角色的存取控制規則。 代理的角色決定哪些實體可見、允許哪些操作、包含哪些欄位，以及是否適用列級政策。
如果此anonymous角色只允許對Products的讀取權限：
-
describe_entities僅在操作中顯示read_records -
create_record，update_record，delete_record不可用 - 只有允許
anonymous的欄位才會出現在結構中
在你的 dab-config.json 中設定角色：
{
"entities": {
"Products": {
"permissions": [
{
"role": "anonymous",
"actions": [
{
"action": "read",
"fields": {
"include": ["ProductId", "ProductName", "Price"],
"exclude": ["Cost"]
}
}
]
},
{
"role": "admin",
"actions": ["*"]
}
]
}
}
}