hs-sql-agent
2.0.2
文件 2.0.2
文件版本
2.0.2 最新
2.0.2 最新
文件 管理

MCP Keys

在 hs-sql-agent 2.0.1 簽發、限制、rotate、clone 與 revoke MCP credentials。

Database boundary 每把 production key 都綁定到一個 Database Management entry。
Tool boundary 只暴露 client 真正需要的 built-in 與 published Custom Tools。
Table boundary 需要時再以 qualified-table whitelist 限制 key 可見資料表。

MCP key 用來驗證 /mcp request，並攜帶 hs-sql-agent runtime authorization scope。它與 Admin user session、OIDC identity 是不同的身份邊界。

2.0.1 正式 built-in tool surface

Key-management service 正式辨識五個 built-in tools：

ToolScope
get_schemasschema discovery
get_tablestable discovery
get_columnscolumn discovery
execute_query_sqlgoverned SELECT execution
execute_dml_sqlgoverned Safe DML

同一 database 下已 publish 的 Custom Tools 也可以依名稱加入 allowlist。請見 Custom Tools。

簽發 key

  1. 設定名稱

    Request 必須有非空白 name，且上限 100 characters。

  2. 綁定 database

    2.0.1 issuance validator 要求 DbManagementId。

  3. 選擇 tools

    選取 built-in tools，以及該 database 已 publish 的 Custom Tools。

  4. 限制 data access

    如果 client 只能看部分資料表，啟用 table whitelist。

  5. 設定 lifecycle controls

    需要時設定 expiration、CORS origins 與 rate-limit mode/overrides。

  6. 複製 plaintext secret

    Lifecycle dialog 關閉前，把新 key 保存到 client secret store。

Issuance 欄位

Field意義
Name操作者辨識 key 的名稱
ExpiresAt選用 expiration；有設定時必須在未來
AllowedToolscomma-separated tool names；空白代表 unrestricted
CorsAllowedOrigins選用的 browser-origin MCP CORS restriction
DbManagementId綁定 database entry；簽發時必填
TableWhitelist選用 comma-separated qualified-table allowlist
RateLimitModeInherit、Custom 或 Unlimited
PermitLimitOverrideCustom per-key rate limit 使用
WindowSecondsOverrideCustom per-key rate limit 使用

保存的 key record 只暴露短 prefix 供辨識。Raw secret 透過 server HMAC secret 驗證，不應被設計成日後再次顯示。

Rotate key

Rotation 會建立 replacement key，並繼承舊 key 的 database/tool/table/CORS/rate-limit scope。

Grace period 可以設 0 到 1440 分鐘：

  • 0 會立即 revoke 舊 key；
  • 正值會在需要時把舊 key expiration 縮短到 grace deadline；
  • replacement 會拿到全新產生的 plaintext secret。

Clone key

Clone 會建立新 key，複製 source key 的 runtime scope，但使用新的 name 與 secret。兩個 client 權限相同但不應共用 credential 時很適合使用。

Clone 後 lifecycle 完全獨立，可以單獨 revoke 或 rotate，不會讓 source key 一起失效。

Revoke key

Revocation 會把 key 標成 inactive，並在 DB commit 前先把 revocation tombstone 寫入 validation-cache path，目的是避免剛 revoke 的 credential 因 stale cache 繼續被接受。

Bootstrap-managed key 不能走一般 UI lifecycle 做 edit、rotate 或 revoke；它的 lifecycle 由 bootstrap configuration 控制。

Rate-limit behavior

Key 可以繼承 runtime key rate-limit policy、使用 custom override，或明確 unlimited。Admin list view 會把 key mode 與目前 security policy 合併後顯示 effective rate limit。

多節點 deployment 若要全域協調限制，請使用 distributed rate-limiter configuration。

DML 與 Elicitation

選取 execute_dml_sql 後，client compatibility requirement 也會改變。MCP client 必須支援 mutation approval 使用的 form Elicitation flow。

授權新 client 使用 DML 前，請先讀 MCP client onboarding。