MCP クライアントの接続

hs-sql-agent は /mcp で Streamable HTTP の MCP エンドポイントを公開します。

クライアントを接続

1. MCP キーを発行

   管理画面で、接続先データベースに結び付けたキーを作成します。無制限の権限が不要なら、利用できるツールとテーブルを必要最小限に絞ってください。

2. 公開 MCP エンドポイントを使用

   クライアントから到達できる URL を指定します。管理画面と MCP エンドポイントが同じホストやポートにあるとは限りません。

3. すべての要求を認証

   以下の MCP 要求ヘッダーでキーを送信します。平文のキーはシークレットとして扱ってください。発行・更新用ダイアログを閉じると、同じ値は再表示されません。

4. 実際に使うクライアントを確認

   まずスキーマ取得とクエリ実行を確認します。DML を有効にする場合は、本番導入前に form Elicitation の動作も別途テストしてください。

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

公開エンドポイント

運用者向け画面と自動生成されるクライアント設定に表示される URL は、次のサーバー設定から取得します。

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

対応する環境変数は Mcp__PublicEndpoint です。付属の Compose 構成では MCP_PUBLIC_ENDPOINT からこの設定へ値を渡します。

自動生成されるクライアント設定

MCP キーを発行、ローテーション、複製すると、管理画面から Claude Desktop、Cursor、一般的な Streamable HTTP クライアント向けの直接接続設定を生成できます。

平文のキーは一時的にしか表示されません。発行・更新用ダイアログを閉じた後、サーバーから同じシークレットを再表示することはできません。

DML への対応は別に確認する

/mcp へ正常に接続できても、DML の承認に対応しているとは限りません。

execute_dml_sql と公開済みの DML Custom Tools では form Elicitation が必要です。本番で DML を許可する前に、実際に導入するクライアントのバージョンで次の両方を確認してください。

1. Elicitation 要求を拒否し、データ変更が確定されないことを確認する。
2. Elicitation 要求を承認し、承認したデータ変更だけが完了することを確認する。

次に読むドキュメント