Built-in MCP Surface 刻意維持精簡。hs-sql-agent 仍只有五個由 MCP Key Scope 管理的 built-in Tool 名稱。
| Tool | 公開輸入 | 用途 |
|---|---|---|
get_schemas | 無 | 探索 Schemas |
get_tables | schemaName: string | 探索可見 Tables |
get_columns | schemaName: string, tableName: string | 探索 Columns 與 Key Metadata |
execute_query_sql | sql: string | 執行一個受治理的 SELECT Query |
execute_dml_sql | sql: string | 原子執行一個或多個已核准 DML |
Published Custom Tools 可以擴充特定資料庫的 Tool Collection，但不算新的 built-in Tools。
授權先於 Discovery
MCP Session 會在 MCP Key 驗證後建立。明確設定的 AllowedTools 會限制可見的 built-in 與 Published Custom Tool 名稱。Database Binding、Table Allowlist、Rate Limit、SQL Concurrency、Policy 與 Audit 仍全部由伺服器控制。
Metadata Tools 不接受模型傳入 Connection String。
execute_query_sql
execute_query_sql(sql: string)只接受一個受支援的 SELECT，並走 Typed Query Pipeline：Parse、Bind、Table Authorization、Policy 與來源語意驗證、Target Capability 證明、Compile immutable Provider Command，最後才執行。
不支援的 SQL 會 fail closed，不會退回 Raw SQL 直接執行。
execute_dml_sql
execute_dml_sql(sql: string)同一個 Tool 現在可接受一個或多個以分號分隔的受支援 DML。這是擴充既有 Tool，而不是新增 execute_dml_sql_batch。
| Statement | 狀態 |
|---|---|
UPDATE | Capability、Policy、核准與重新驗證全部通過時支援 |
DELETE | Capability、Policy、核准與重新驗證全部通過時支援 |
INSERT ... VALUES | 使用 immutable-payload approval semantics |
INSERT ... SELECT | 在 source-rowset approval semantics 完成前 fail closed |
Multi-statement Request 會先驗證整個 Batch、建立每個 Statement 的 Evidence、只請求一次 Atomic Transaction 核准，再由伺服器開啟單一 Transaction。每個 Statement 在修改前重新驗證並依原始順序執行；任何一個 Statement 失敗或 stale，整個 Transaction 都 rollback。
Client-supplied Transaction-control SQL 會被拒絕。
核准 Transport
MCP Elicitation 是第一方預設，但 DML 架構不再綁死 Elicitation。Standard Hosting 可選官方 Webhook adapter；Modular Host 可註冊 HsSqlAgent.Approvals.Webhook 或自己的 IDmlApprovalProvider。
非同步 Provider 可回傳 Pending。Durable Completion 仍由伺服器掌握，任何後續 commit 前都會重新驗證目前授權、設定、Policy、Plan、Row Set 與 affected-row Evidence。
另見 Safe DML。