SQL MCP Server のデータ操作言語 (DML) ツール

SQL モデル コンテキスト プロトコル (MCP) サーバーは、7 つのデータ操作言語 (DML) ツールを AI エージェントに公開します。 これらのツールは、データベース操作 (レコードの作成、読み取り、更新、削除、データの集計、ストアド プロシージャの実行など) に対して型指定された CRUD サーフェスを提供します。 すべてのツールは、ロールベースのアクセス制御 (RBAC)、エンティティのアクセス許可、および構成で定義されているポリシーを尊重します。

DML ツールとは

DML (データ操作言語) ツールは、レコードの作成、読み取り、更新、削除、データの集計、ストアド プロシージャの実行などのデータ操作を処理します。 スキーマを変更する DDL (データ定義言語) とは異なり、DML は既存のテーブルとビューのデータ プレーンでのみ機能します。

7 つの DML ツールは次のとおりです。

• describe_entities - 使用可能なエンティティと操作を検出します
• create_record - 新しい行を挿入します
• read_records - テーブルとビューのクエリ
• update_record - 既存の行を変更します
• delete_record - 行を削除します
• execute_entity - ストアド プロシージャを実行する
• aggregate_records - 集計クエリを実行します

DML ツールがグローバルかつエンティティに対して有効になっている場合、SQL MCP Server は MCP プロトコルを介してそれらを公開します。 エージェントは、データベース スキーマと直接やり取りすることはありません。エージェントは、データ API ビルダーの抽象化レイヤーを介して動作します。

ツール

ツール一覧の応答

エージェントが list_toolsを呼び出すと、SQL MCP Server は次を返します。

{
  "tools": [
    { "name": "describe_entities" },
    { "name": "create_record" },
    { "name": "read_records" },
    { "name": "update_record" },
    { "name": "delete_record" },
    { "name": "execute_entity" },
    { "name": "aggregate_records" }
  ]
}

エンティティの説明

現在のロールで使用できるエンティティを返します。 各エントリには、フィールド名、説明、および許可される操作が含まれます。 このツールでは、データベースのクエリは実行されません。 代わりに、構成ファイルからビルドされたメモリ内構成から読み取ります。

パラメーター

要求の例

{
  "method": "tools/call",
  "params": {
    "name": "describe_entities",
    "arguments": {
      "entities": ["Products"]
    }
  }
}

応答の例

{
  "entities": [
    {
      "name": "Products",
      "description": "Product catalog with pricing and inventory",
      "fields": [
        {
          "name": "ProductId",
          "description": "Unique product identifier"
        },
        {
          "name": "ProductName",
          "description": "Display name of the product"
        },
        {
          "name": "Price",
          "description": "Retail price in USD"
        }
      ],
      "operations": [
        "read_records",
        "update_record"
      ]
    }
  ]
}

create_record

テーブルに新しい行を作成します。 現在のロールのエンティティに対する作成権限が必要です。 このツールは、エンティティ スキーマに対する入力を検証し、フィールド レベルのアクセス許可を適用し、作成ポリシーを適用して、生成された値を持つ作成済みレコードを返します。

パラメーター

レコードを読み取る

テーブルまたはビューに対してクエリを実行します。 フィルター処理、並べ替え、改ページ位置指定、およびフィールドの選択をサポートします。 このツールは、構造化されたパラメーターから確定的な SQL を構築し、読み取りアクセス許可とフィールド プロジェクションを適用し、行レベルのセキュリティ ポリシーを適用します。

パラメーター

ページネーションの応答

使用可能な結果が増えると、応答には after カーソルが含まれます。 この値を次の要求の after パラメーターとして渡して、次のページをフェッチします。

{
  "value": [ ... ],
  "after": "W3siRW50aXR5TmFtZ..."
}

after フィールドが存在すると、より多くのページが存在します。 afterが存在しない場合は、最後のページに到達しました。

JOIN 演算操作

read_records ツールは、1 つのテーブルまたはビュー用に設計されています。 そのため、このツールでは JOIN 操作はサポートされていません。 この設計は、責任を分離し、パフォーマンスを向上させ、セッションのコンテキスト ウィンドウへの影響を制限するのに役立ちます。

ただし、JOIN 操作はエッジ ケースではなく、Data API Builder (DAB) では GraphQL エンドポイントを介した高度なクエリが既にサポートされています。 より複雑なクエリの場合は、テーブルではなくビューを使用することをお勧めします。 execute_entity ツールを使用してストアド プロシージャを実行し、パラメーター化されたクエリをカプセル化することもできます。

レコード更新

既存の行を変更します。 更新するには、主キーとフィールドが必要です。 このツールは、主キーが存在することを検証し、更新のアクセス許可とポリシーを適用し、現在のロールが変更できるフィールドのみを更新します。

パラメーター

レコードを削除

既存の行を削除します。 主キーが必要です。 このツールは、主キーが存在することを検証し、削除のアクセス許可とポリシーを適用し、トランザクションをサポートして安全な削除を実行します。

パラメーター

エンティティを実行

ストアド プロシージャを実行します。 入力パラメーターと出力結果をサポートします。 このツールは、プロシージャ署名に対して入力パラメーターを検証し、実行アクセス許可を適用し、パラメーターを安全に渡します。

パラメーター

レコード集約

テーブルとビューに対して集計クエリを実行します。 count、sum、average、minimum、maximum などの一般的な集計関数をサポートします。 このツールは、構造化されたパラメーターから確定的な SQL を構築し、読み取りアクセス許可とフィールド プロジェクションを適用し、行レベルのセキュリティ ポリシーを適用します。

パラメーター

例: groupby と having を使用してカウントする

{
  "method": "tools/call",
  "params": {
    "name": "aggregate_records",
    "arguments": {
      "entity": "Todo",
      "function": "count",
      "field": "*",
      "groupby": ["UserId"],
      "having": { "gt": 2 }
    }
  }
}

aggregate-records ツールは、ブール値として、またはより多くの設定を持つオブジェクトとして構成できます。

{
  "runtime": {
    "mcp": {
      "dml-tools": {
        "aggregate-records": {
          "enabled": true,
          "query-timeout": 30
        }
      }
    }
  }
}

query-timeout プロパティは、最大実行時間を秒単位で指定します (範囲: 1 ~ 600)。 この設定は、実行時間の長い集計クエリが過剰なリソースを消費するのを防ぐのに役立ちます。

ランタイム構成

dab-config.jsonのランタイム セクションで DML ツールをグローバルに構成します。

{
  "runtime": {
    "mcp": {
      "enabled": true,
      "path": "/mcp",
      "dml-tools": {
        "describe-entities": true,
        "create-record": true,
        "read-records": true,
        "update-record": true,
        "delete-record": true,
        "execute-entity": true,
        "aggregate-records": true
      }
    }
  }
}

runtime.mcp.dml-toolsの各ツール プロパティは、trueまたはfalseを受け入れます。 aggregate-records ツールでは、enabledとquery-timeoutを使用したオブジェクト形式もサポートされています。

{
  "runtime": {
    "mcp": {
      "enabled": true,
      "dml-tools": {
        "describe-entities": true,
        "create-record": true,
        "read-records": true,
        "update-record": true,
        "delete-record": true,
        "execute-entity": true,
        "aggregate-records": {
          "enabled": true,
          "query-timeout": 30
        }
      }
    }
  }
}

すべての DML ツールを一度に有効または無効にするには、 "dml-tools" を true または false に設定します。

CLI を使用する

データ API ビルダー CLI を使用してプロパティを個別に設定します。

dab configure --runtime.mcp.enabled true
dab configure --runtime.mcp.path "/mcp"
dab configure --runtime.mcp.dml-tools.describe-entities true
dab configure --runtime.mcp.dml-tools.create-record true
dab configure --runtime.mcp.dml-tools.read-records true
dab configure --runtime.mcp.dml-tools.update-record true
dab configure --runtime.mcp.dml-tools.delete-record true
dab configure --runtime.mcp.dml-tools.execute-entity true
dab configure --runtime.mcp.dml-tools.aggregate-records.enabled true
dab configure --runtime.mcp.dml-tools.aggregate-records.query-timeout 30

ツールの無効化

ランタイム レベルでツールを無効にすると、エンティティのアクセス許可やロールの構成に関係なく、エージェントには表示されません。 この設定は、厳密な運用境界が必要な場合に便利です。

一般的なシナリオ

• 運用環境でのデータ損失を防ぐために delete-record を無効にする
• 読み取り専用レポート エンドポイントの create-record を無効にする
• ストアド プロシージャが使用されていない場合に execute-entity を無効にする
• 集計クエリが必要ない場合に aggregate-records を無効にする

ツールがグローバルに無効になっている場合、ツールは list_tools 応答から非表示になり、呼び出すことはできません。

エンティティ設定

エンティティは、明示的に制限しない限り、MCP に自動的に参加します。 エンティティの mcp プロパティは、その MCP 参加を制御します。 明示的な制御にはオブジェクト形式を使用します。

オブジェクトの形式

{
  "entities": {
    "Products": {
      "mcp": {
        "dml-tools": true
      }
    },
    "SensitiveData": {
      "mcp": {
        "dml-tools": false
      }
    }
  }
}

エンティティに mcp を指定しない場合、MCP がグローバルに有効になっている場合、DML ツールは既定で有効になります。

ストアド プロシージャ用のカスタム ツール

ストアド プロシージャ エンティティの場合は、 custom-tool プロパティを使用して、プロシージャを名前付き MCP ツールとして登録します。

{
  "entities": {
    "GetBookById": {
      "source": {
        "type": "stored-procedure",
        "object": "dbo.get_book_by_id"
      },
      "mcp": {
        "custom-tool": true
      }
    }
  }
}

ツールごとのコントロールのスコープ

ツールごとのトグルは、 runtime.mcp.dml-toolsのグローバル ランタイム レベルでのみ構成されます。

エンティティ レベルでは、 mcp はブールゲートか、 dml-tools プロパティと custom-tool プロパティを持つオブジェクトです。

{
  "entities": {
    "AuditLogs": {
      "mcp": {
        "dml-tools": false
      }
    }
  }
}

{
  "runtime": {
    "mcp": {
      "dml-tools": {
        "describe-entities": true,
        "create-record": true,
        "read-records": true,
        "update-record": true,
        "delete-record": false,
        "execute-entity": true,
        "aggregate-records": true
      }
    }
  }
}

ツールは、グローバルに有効になっており、エンティティで DML ツールが許可されている場合にのみ使用できます。

RBAC の統合

すべての DML ツール操作では、ロールベースのアクセス制御規則が適用されます。 エージェントのロールによって、表示されるエンティティ、許可される操作、含まれるフィールド、および行レベルのポリシーが適用されるかどうかが決まります。

anonymous ロールがProductsに対する読み取りアクセス許可のみを許可する場合:

• describe_entities 操作に read_records のみが表示される
• create_record、 update_record、および delete_record は使用できません
• anonymousに許可されているフィールドのみがスキーマに表示されます

dab-config.jsonで役割を構成します。

{
  "entities": {
    "Products": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "fields": {
                "include": ["ProductId", "ProductName", "Price"],
                "exclude": ["Cost"]
              }
            }
          ]
        },
        {
          "role": "admin",
          "actions": [
            {
              "action": "*"
            }
          ]
        }
      ]
    }
  }
}

関連コンテンツ

• SQL MCP Server の概要
• SQL MCP Server へのセマンティック記述の追加
• データ API ビルダー (DAB) 構成リファレンス
• エンティティ レベルの MCP 構成
• ランタイム MCP 構成
• SQL MCP Server を Azure Container Apps
• Data API Builder バージョン 2.0 の新機能