hs-sql-agent
2.0.3
ドキュメント 2.0.3
ドキュメントバージョン
2.0.3 最新
2.0.2 サポート中 2.0.3 最新
ドキュメント 管理

データベース管理

hs-sql-agent 2.0.2 から公開するデータベース接続を設定・運用します。

Database Management は、後から MCP キーに紐付けるデータベース接続を管理するための管理画面です。データベースエントリにはプロバイダーと接続メタデータを保存し、MCP クライアントがリクエストごとに任意の接続文字列を渡すことはできません。

対応プロバイダー

2.0.2 は共通 SQL プロバイダーランタイムを通じて、次のプロバイダー識別子に対応します。

  • PostgreSQL
  • MySQL
  • SQL Server
  • Oracle
  • SQLite
  • Firebird

設定したプロバイダーは、Query / DML 実行で使用する SQL 方言と capability profile も決定します。

接続フィールド

2.0.2 のデータベース要求モデルには、次のフィールドがあります。

フィールド用途
Name運用者向けの接続名
SqlProviderデータベースプロバイダー／方言
Hostデータベースホスト、またはプロバイダー固有の場所
Port文字列として扱うプロバイダーのポート
Usernameデータベースへのログインユーザー
Passwordデータベースパスワード。不要なのは SQLite のみ
Databaseプロバイダーの接続文字列ファクトリが利用するデータベース／カタログ／ファイル値
ExtraSettings任意のプロバイダー固有接続設定

CreatedBy と UpdatedBy もサービス要求モデルに存在しますが、これらはコントロールプレーン側のメタデータであり、MCP クライアントが操作する値ではありません。

接続を作成する

Runtime → Database Management で次の手順を実行します。

  1. データベースエントリを作成し、運用時に判別しやすい名前を付けます。
  2. プロバイダーを選択します。
  3. プロバイダーの接続情報を入力します。
  4. hs-sql-agent に実際に必要な権限だけを持つ専用データベースアカウントを使用します。
  5. 保存後、本番用 MCP キーを紐付ける前に接続を確認します。

API は空の名前を拒否します。また SQLite を除くすべてのプロバイダーで、バックエンドはパスワード未指定を拒否します。

接続をテストする

管理ランタイムには接続テスト機能があります。既存の Database Management エントリをテストすると、サーバーは保存済み接続情報を読み込み、保存パスワードを復号し、プロバイダー用の接続文字列を組み立て直して接続テストを実行します。

接続テストが失敗した場合、MCP SQL の動作を調べる前に、まず接続／設定の問題として扱ってください。

代表的な原因は次のとおりです。

  • hs-sql-agent プロセスからホストまたはポートへ到達できない
  • データベース／カタログ名が間違っている
  • 認証情報が無効
  • ExtraSettings に必要な TLS／暗号化設定がない
  • データベースのファイアウォールまたはネットワークポリシー
  • プロバイダー固有の認証要件

メタデータの参照

/runtime/db-management に対する view 権限がある場合、Admin API から保存済み接続のプロバイダーメタデータを参照できます。

  • スキーマ
  • スキーマ内のテーブル
  • テーブル内のカラム

これらの操作では、保存済みデータベースエントリからプロバイダー接続を構築します。MCP のスキーマ探索とは別の機能であり、MCP 側ではさらに認証済みキーのテーブルホワイトリストとセマンティック情報が適用されます。

MCP キーを紐付ける

本番用 MCP キーは Database Management エントリを参照する必要があります。その接続が、そのキーのデータベース境界になります。

MCP キー側でさらに次の制限を加えられます。

  • ツールの許可リスト
  • テーブルホワイトリスト
  • CORS オリジン
  • 有効期限
  • レート制限モード／上書き値

詳しくは MCP キー を参照してください。

テーブルホワイトリストはデータベース側には保存しません

Database Management が定義するのは接続です。テーブル単位の認可は MCP キーに適用します。

この分離により、複数の MCP キーが同じ物理データベース接続を共有しながら、異なるテーブル／ツール範囲を持てます。たとえば、1 つのキーはレポート用テーブルの読み取りだけを公開し、別の運用ワークフロー用キーには別のテーブル群と DML を公開できます。

セマンティックメタデータはデータベースモデルに属します

テーブル／カラムの表示名、説明、同義語、リレーション、メトリクスは Database Management エントリに関連付けられます。スキーマ探索では、物理データベースのスキーマを変更せずに MCP から見えるメタデータを補強できます。

詳しくは セマンティックメタデータ を参照してください。

権限

2.0.2 の Admin API は、Database Management の各操作に明示的な権限を適用します。

操作権限
接続とメタデータの一覧／参照/runtime/db-management → view
作成/runtime/db-management → create
編集/runtime/db-management → edit
削除/runtime/db-management → delete
セマンティックメタデータの参照/runtime/db-management/semantic → view
セマンティックメタデータの編集/runtime/db-management/semantic → edit

したがって、管理ユーザーがサインイン済みであるだけでは不十分で、各操作ごとに認可が確認されます。

運用上の推奨事項

Database Management エントリには安定した名前を使用し、利用中の MCP キーの背後で接続先の意味を変えないでください。キーのデータベース境界を変更する必要がある場合は、明示的なキーのライフサイクル操作として扱い、テーブル／ツール範囲を再確認することを推奨します。

データベース認証情報やプロバイダー固有のシークレットは機密情報として扱ってください。Custom Tool のテンプレートやクライアント設定には含めず、クライアントに渡すのは MCP エンドポイントと MCP キーだけにしてください。