hs-sql-agent は /mcp で Streamable HTTP の MCP エンドポイントを公開します。内蔵の管理画面を使う場合、通常は endpoint や header を手作業で組み立てる必要はありません。キー発行後に hs-sql-agent が生成する設定を、そのまま MCP クライアントへ貼り付けます。
推奨する接続手順
- MCP キーを発行
Runtime → MCP Keys を開き、対象データベース用のキーを作成します。クライアントに必要なツールとテーブルだけを許可してください。
- 一度だけ表示される Save and connect を使う
Issue Key が成功すると、hs-sql-agent は平文キーと生成済みのクライアント設定をすぐに表示します。管理画面から平文値を取得できるのはこのタイミングだけです。
- クライアントを選んで設定をコピー
Claude Desktop、Cursor、Visual Studio Code、Generic HTTP のいずれかを選び、対応する Copy … config を押します。コピーされる JSON には MCP endpoint と
X-MCP-Server-Keyがすでに含まれています。 - 貼り付けて接続し、必要なら DML を確認
コピーした 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 の成功後、現在の管理画面には次の 4 つの設定タブがあります。
- Claude Desktop — 直接 HTTP 接続用の
mcpServersエントリ - Cursor — HTTP
mcpServersエントリ - Visual Studio Code —
serversエントリ - Generic HTTP — Streamable HTTP 接続オブジェクト
どの形式にも、サーバーで設定した endpoint と今回生成された MCP キーが含まれます。通常は JSON を手作業で組み立てる必要はありません。
Generic / 手動認証の参照
クライアント側で別の外側の設定形式が必要な場合は、Generic HTTP の出力を参照してください。プロトコル上の認証は次の header です。
X-MCP-Server-Key: <MCP key>DML への対応は別に確認する
/mcp へ正常に接続できても、DML の承認に対応しているとは限りません。
execute_dml_sql と公開済みの DML Custom Tools では form Elicitation が必要です。本番で DML を許可する前に、実際に導入するクライアントのバージョンで次の両方を確認してください。
- Elicitation 要求を拒否し、データ変更がコミットされないことを確認する。
- Elicitation 要求を承認し、承認したデータ変更だけが完了することを確認する。