排錯時先確認「是哪一個安全或執行邊界拒絕了這次請求」。hs-sql-agent 在多個位置刻意採用 fail-closed，因此被拒絕往往代表設定或 capability 不相容，不一定是暫時性的 SQL 執行錯誤。
本機可以連線，但產生的設定 URL 錯誤
檢查 MCP_PUBLIC_ENDPOINT。它必須是外部用戶端實際可到達、包含 /mcp 的 HTTP / HTTPS 絕對 URL。如果反向代理讓管理介面與 MCP 使用不同位置，不要直接拿管理介面的 URL 猜 MCP 端點。
查詢可用，但 DML 被拒絕
MCP 已連線成功不代表 Elicitation 一定可用。execute_dml_sql 與已發布的 DML Custom Tools 都需要 form Elicitation。請用實際使用的用戶端版本，同時驗證拒絕（Decline）與接受（Accept）兩條流程。
重新啟動後，登入或 MFA 狀態失效
檢查 DATA_PROTECTION_KEY_PATH 是否已持久化。如果每次替換容器都換掉 ASP.NET Core data-protection keys，既有受保護的登入與 MFA 狀態可能無法解密。
多執行個體行為不一致
確認需要跨節點協調的 provider 是否仍使用 Memory。分散式部署應替必須跨節點一致的快取、速率限制、安全政策同步、外送同步與 SQL 並行協調使用共用 provider。
Prometheus 不在應用程式連接埠
啟用 Prometheus 後會使用獨立監聽端點；範例連接埠是 9000。不要預期指標會自動出現在主要 API 監聽端點。
資料庫 CLI 能執行的 SQL，卻被 hs-sql-agent 拒絕
這可能是正常行為。Provider 支援範圍受編譯器契約約束；尚未能表示、或無法證明語意安全的語法或 capability 會被拒絕，而不是直接把任意供應商專屬 SQL 傳給資料庫執行。