Tools für die Datenmanipulationssprache (DATA Manipulation Language, DML) in SQL MCP Server

Der SQL Model Context Protocol (MCP)-Server macht sieben DML-Tools (Data Manipulation Language) FÜR KI-Agents verfügbar. Diese Tools bieten eine typierte CRUD-Oberfläche für Datenbankvorgänge: Erstellen, Lesen, Aktualisieren und Löschen von Datensätzen, Aggregieren von Daten und Ausführen gespeicherter Prozeduren. Alle Tools respektieren rollenbasierte Zugriffssteuerung (RBAC), Entitätsberechtigungen und Richtlinien, die in Ihrer Konfiguration definiert sind.

Was sind DML-Tools?

DML-Tools (Data Manipulation Language) behandeln Datenvorgänge: Erstellen, Lesen, Aktualisieren und Löschen von Datensätzen, Aggregieren von Daten und Ausführen gespeicherter Prozeduren. Im Gegensatz zu DDL (Data Definition Language), die das Schema ändert, funktioniert DML ausschließlich auf der Datenebene in vorhandenen Tabellen und Ansichten.

Die sieben DML-Tools sind:

• describe_entities – Ermittelt verfügbare Entitäten und Vorgänge
• create_record - Fügt neue Zeilen ein.
• read_records - Abfragen von Tabellen und Ansichten
• update_record - Ändert vorhandene Zeilen
• delete_record - Entfernt Zeilen
• execute_entity - Führt gespeicherte Prozeduren aus.
• aggregate_records - Führt Aggregationsabfragen aus

Wenn DML-Tools global und für eine Entität aktiviert sind, macht SQL MCP Server sie über das MCP-Protokoll verfügbar. Agents interagieren niemals direkt mit Ihrem Datenbankschema – sie arbeiten über die Abstraktionsebene des Daten-API-Generators.

Die Tools

Antwort auf list_tools

Wenn ein Agent aufruft list_tools, gibt SQL MCP Server Folgendes zurück:

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

describe_entities

Gibt die Entitäten zurück, die für die aktuelle Rolle verfügbar sind. Jeder Eintrag enthält Feldnamen, Beschreibungen und zulässige Vorgänge. Dieses Tool fragt die Datenbank nicht ab. Stattdessen liest sie aus der speicherinternen Konfiguration, die aus Ihrer Konfigurationsdatei erstellt wurde.

Parameter

Beispielanforderung

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

Beispielantwort

{
  "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

Erstellt eine neue Zeile in einer Tabelle. Erfordert die Berechtigung zum Erstellen der Entität für die aktuelle Rolle. Das Tool überprüft Eingaben für das Entitätsschema, erzwingt Berechtigungen auf Feldebene, wendet Richtlinien an und gibt den erstellten Datensatz mit allen generierten Werten zurück.

Parameter

Datensätze_lesen

Fragt eine Tabelle oder Ansicht ab. Unterstützt das Filtern, Sortieren, Paginieren und Auswählen von Feldern. Das Tool erstellt deterministische SQL aus strukturierten Parametern, wendet Leseberechtigungen und Feldprojektionen an und erzwingt Sicherheitsrichtlinien auf Zeilenebene.

Parameter

Paginierungsantwort

Wenn weitere Ergebnisse verfügbar sind, enthält die Antwort einen after Cursor. Übergeben Sie diesen Wert als after Parameter in der nächsten Anforderung, um die nächste Seite abzurufen.

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

Das Vorhandensein des after Felds gibt an, dass mehr Seiten vorhanden sind. Wenn after fehlt, haben Sie die letzte Seite erreicht.

JOIN-Vorgänge

Das read_records Tool wurde für eine einzelne Tabelle oder Ansicht entwickelt. Daher werden JOIN-Vorgänge in diesem Tool nicht unterstützt. Dieses Design hilft dabei, Verantwortung zu isolieren, die Leistung zu verbessern und die Auswirkungen auf das Kontextfenster Ihrer Sitzung einzuschränken.

JOIN-Vorgänge sind jedoch kein Edgefall, und der Daten-API-Generator (DATA API Builder, DAB) unterstützt bereits anspruchsvolle Abfragen über den GraphQL-Endpunkt. Für komplexere Abfragen empfehlen wir die Verwendung einer Ansicht anstelle einer Tabelle. Sie können das execute_entity Tool auch verwenden, um gespeicherte Prozeduren auszuführen, um parametrisierte Abfragen zu kapseln.

Datensatz_aktualisieren

Ändert eine vorhandene Zeile. Erfordert die Aktualisierung des Primärschlüssels und der Felder. Das Tool überprüft, ob der Primärschlüssel vorhanden ist, erzwingt Updateberechtigungen und Richtlinien und aktualisiert nur Felder, die die aktuelle Rolle ändern kann.

Parameter

Datensatz löschen

Entfernt eine vorhandene Zeile. Erfordert den Primärschlüssel. Das Tool überprüft, ob der Primärschlüssel vorhanden ist, erzwingt Löschberechtigungen und -richtlinien und führt einen sicheren Löschvorgang mit Transaktionsunterstützung durch.

Parameter

execute_entity

Führt eine gespeicherte Prozedur aus. Unterstützt Eingabeparameter und Ausgabeergebnisse. Das Tool überprüft Eingabeparameter anhand der Prozedursignatur, erzwingt Ausführungsberechtigungen und übergibt Parameter sicher.

Parameter

Datensätze zusammenfassen

Führt Aggregationsabfragen für Tabellen und Ansichten aus. Unterstützt allgemeine Aggregatfunktionen wie Anzahl, Summe, Mittelwert, Minimum und Maximum. Das Tool erstellt deterministische SQL aus strukturierten Parametern, wendet Leseberechtigungen und Feldprojektionen an und erzwingt Sicherheitsrichtlinien auf Zeilenebene.

Parameter

Beispiel: Zählen mit "groupby" und "Having"

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

Das aggregate-records Tool kann als boolescher Wert oder als Objekt mit weiteren Einstellungen konfiguriert werden:

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

Die query-timeout Eigenschaft gibt die maximale Ausführungszeit in Sekunden an (Bereich: 1 bis 600). Diese Einstellung verhindert, dass lange ausgeführte Aggregationsabfragen übermäßige Ressourcen verbrauchen.

Laufzeitkonfiguration

Konfigurieren Sie DML-Tools global im Laufzeitabschnitt Ihrer dab-config.json:

{
  "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
      }
    }
  }
}

Jede Tooleigenschaft unter runtime.mcp.dml-tools akzeptiert true oder false. Das aggregate-records Tool unterstützt außerdem ein Objektformat mit enabled und 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
        }
      }
    }
  }
}

Um alle DML-Tools auf einmal zu aktivieren oder zu deaktivieren, legen Sie dieses Element "dml-tools" auf true oder false fest.

Verwenden der CLI

Eigenschaften individuell festlegen mithilfe der Data API-Generator-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

Deaktivieren von Tools

Wenn Sie ein Tool auf Laufzeitebene deaktivieren, wird es nie für Agents angezeigt, unabhängig von Entitätsberechtigungen oder Rollenkonfiguration. Diese Einstellung ist nützlich, wenn Sie strenge betriebstechnische Grenzen benötigen.

Häufige Szenarien

• Deaktivieren delete-record , um Datenverlust in der Produktion zu verhindern
• Deaktivieren Sie create-record für schreibgeschützte Berichts-Endpunkte
• Deaktivieren execute-entity , wenn gespeicherte Prozeduren nicht verwendet werden
• Deaktivieren, aggregate-records wenn Aggregationsabfragen nicht benötigt werden

Wenn ein Tool global deaktiviert ist, wird das Tool in der list_tools Antwort ausgeblendet und kann nicht aufgerufen werden.

Entitätseinstellungen

Entitäten nehmen automatisch an MCP teil, es sei denn, Sie schränken sie explizit ein. Die mcp Eigenschaft einer Entität steuert deren MCP-Teilnahme. Verwenden Sie das Objektformat für die explizite Steuerung.

Objektformat

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

Wenn Sie mcp bei einer Entität nicht angeben, werden die DML-Tools standardmäßig aktiviert, wenn MCP global aktiviert ist.

Benutzerdefinierte Tools für gespeicherte Prozeduren

Verwenden Sie für Entitäten gespeicherter Prozeduren die custom-tool Eigenschaft, um die Prozedur als benanntes MCP-Tool zu registrieren:

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

Umfang der Steuerung für jedes Tool

Die Umschalter pro Tool werden nur auf der globalen Laufzeitebene unter runtime.mcp.dml-tools konfiguriert.

Auf Entitätsebene ist mcp ein boolesches Gatter oder ein Objekt mit den Eigenschaften dml-tools und 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
      }
    }
  }
}

Ein Tool ist nur verfügbar, wenn es global aktiviert ist und die Entität DML-Tools zulässt.

RBAC-Integration

Jeder DML-Toolvorgang erzwingt Ihre rollenbasierten Zugriffssteuerungsregeln. Die Rolle eines Agents bestimmt, welche Entitäten sichtbar sind, welche Vorgänge zulässig sind, welche Felder enthalten sind und ob Richtlinien auf Zeilenebene gelten.

Wenn die anonymous Rolle nur Leseberechtigungen zulässt für Products:

• describe_entities wird nur in Vorgängen angezeigt read_records
• create_record, update_recordund delete_record sind nicht verfügbar
• Nur Felder, die im Schema anonymous erlaubt sind, werden angezeigt.

Konfigurieren Sie Rollen in Ihrem dab-config.json:

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

Verwandte Inhalte

• Übersicht über SQL MCP Server
• Hinzufügen von semantischen Beschreibungen zu SQL MCP Server
• Konfigurationsreferenz für den Daten-API-Generator (DAB)
• MCP-Konfiguration auf Entitätsebene
• MCP-Laufzeitkonfiguration
• Bereitstellen von SQL MCP Server in Azure-Container-Apps
• Neuerungen in Data API Builder, Version 2.0