連接 MCP 用戶端

hs-sql-agent 在 /mcp 提供 Streamable HTTP MCP 端點。使用內建管理介面時，正常的連線方式不是自己手動拼 endpoint 與 header，而是讓 hs-sql-agent 在簽發金鑰後直接產生可貼進 MCP 用戶端的設定。

建議的連線流程

1. 簽發 MCP 金鑰

   進入 Runtime → MCP Keys，為目標資料庫建立金鑰，並只開放用戶端真正需要的工具與資料表。

2. 使用一次性的 Save and connect 對話框

   按下 Issue Key 成功後，hs-sql-agent 會立即顯示明文金鑰與產生好的用戶端設定。這是管理介面唯一能取得該明文值的時機。

3. 選擇 MCP 用戶端並複製設定

   切到 Claude Desktop、Cursor、Visual Studio Code 或 Generic HTTP 分頁，再按對應的 Copy … config。複製出的 JSON 已經包含 MCP endpoint 與 X-MCP-Server-Key，不需要自己再組 header。

4. 貼進用戶端並驗證

   把複製的 JSON 貼進 MCP 用戶端設定後連線。如果這把金鑰可以執行 DML，正式使用前還要實測 form Elicitation 的拒絕與接受兩條流程。

產生設定時使用的公開端點

用戶端設定中的 URL 來自伺服器的公開端點設定：

{
  "Mcp": {
    "PublicEndpoint": "https://sql-agent.example.com/mcp"
  }
}

對應的環境變數是 Mcp__PublicEndpoint；專案提供的 Compose 設定會把 MCP_PUBLIC_ENDPOINT 對應到這個值。

正式環境請在簽發正式 MCP 金鑰之前先把它設成用戶端真正可連線、且包含 /mcp 的 URL。管理介面會從 GET /api/runtime/client-config 讀取此值，並直接放進複製出的設定。

對話框目前會產生什麼

Issue、Rotate 或 Duplicate 成功後，目前管理介面提供四種設定：

• Claude Desktop — 直接 HTTP 的 mcpServers 項目；
• Cursor — HTTP mcpServers 項目；
• Visual Studio Code — servers 項目；
• Generic HTTP — Streamable HTTP 連線物件。

四種輸出都會帶入伺服器設定的 endpoint 與該次產生的 MCP 金鑰。一般情況不需要手動重建這些 JSON。

Generic / 手動驗證參考

如果某個 MCP 用戶端需要不同的外層設定格式，可用 Generic HTTP 分頁作為參考。協定層的驗證方式是：

X-MCP-Server-Key: <MCP key>

DML 相容性需要另外確認

成功連接 /mcp，不代表用戶端也支援 DML 核准。

execute_dml_sql 與已發布的 DML Custom Tools 需要 form Elicitation。正式環境允許 DML 前，請使用實際安裝的用戶端版本驗證以下兩種情況：

1. 拒絕 Elicitation 要求，確認資料修改沒有提交。
2. 接受 Elicitation 要求，確認只有已核准的資料修改會完成。

接下來閱讀