MCP 金鑰用來驗證送往 /mcp 的請求，並攜帶 hs-sql-agent 執行階段所需的授權範圍。它和管理端使用者工作階段、OIDC 身分屬於不同的安全邊界。
hs-sql-agent 內建工具
金鑰管理服務正式辨識五個內建工具：
| 工具 | 用途 |
|---|---|
get_schemas | 取得 schema 清單 |
get_tables | 取得資料表清單 |
get_columns | 取得欄位清單 |
execute_query_sql | 執行受治理的 SELECT |
execute_dml_sql | 執行受治理的 Safe DML |
同一資料庫下已發布的 Custom Tools 也可以依名稱加入允許清單。請見 Custom Tools。
簽發金鑰
- 設定名稱
請求必須提供非空白名稱，上限為 100 個字元。
- 綁定資料庫
hs-sql-agent 的簽發驗證要求提供 DbManagementId。
- 選擇工具
選取需要的內建工具，以及該資料庫已發布的 Custom Tools。
- 限制資料存取
如果用戶端只能查看部分資料表，請啟用資料表白名單。
- 設定生命週期限制
需要時可設定到期時間、CORS 來源，以及速率限制模式或覆寫值。
- 複製明文密鑰
關閉生命週期對話框前，先把新金鑰保存到用戶端的安全密鑰儲存區。
簽發欄位
| 欄位 | 意義 |
|---|---|
Name | 方便管理者辨識金鑰的名稱 |
ExpiresAt | 選用的到期時間；有設定時必須是未來時間 |
AllowedTools | 以逗號分隔的工具名稱；空白代表不限制 |
CorsAllowedOrigins | 選用的瀏覽器來源 MCP CORS 限制 |
DbManagementId | 綁定的資料庫項目；簽發時必填 |
TableWhitelist | 選用、以逗號分隔的完整限定資料表白名單 |
RateLimitMode | Inherit、Custom 或 Unlimited |
PermitLimitOverride | Custom 模式下每把金鑰的請求上限 |
WindowSecondsOverride | Custom 模式下的時間視窗秒數 |
資料庫中保存的金鑰紀錄只會暴露短 prefix 供辨識。原始密鑰由伺服器端 HMAC secret 驗證，不應設計成之後還能再次顯示。
輪替金鑰
輪替會建立一把替代金鑰，並繼承舊金鑰的資料庫、工具、資料表、CORS 與速率限制範圍。
寬限期可設為 0 到 1440 分鐘：
0會立即撤銷舊金鑰；- 正值會在需要時把舊金鑰的到期時間縮短到寬限期限；
- 替代金鑰會取得全新產生的明文密鑰。
複製金鑰
複製會建立一把新金鑰，沿用來源金鑰的執行階段權限範圍，但使用新的名稱與密鑰。當兩個用戶端需要相同權限、但不應共用同一份憑證時很適合使用。
複製後兩把金鑰的生命週期完全獨立，可以各自撤銷或輪替，不會讓來源金鑰一起失效。
撤銷金鑰
撤銷會把金鑰標記為停用，並在資料庫交易提交前先把撤銷標記（tombstone）寫入驗證快取路徑，避免剛撤銷的憑證因舊快取仍被接受。
由 bootstrap 設定管理的金鑰不能透過一般管理介面編輯、輪替或撤銷；它的生命週期由 bootstrap configuration 控制。
速率限制行為
金鑰可以繼承執行階段的預設速率限制政策、使用自訂覆寫值，或明確設為不限速。管理端清單會把金鑰模式與目前的安全政策合併後，顯示實際生效的速率限制。
多節點部署若需要全域協調限制，請使用分散式速率限制設定。
DML 與 Elicitation
開放 execute_dml_sql 後，用戶端相容性要求也會提高。MCP 用戶端必須支援資料修改核准流程所使用的 form Elicitation。
授權新的用戶端使用 DML 前，請先閱讀 MCP 用戶端連線。