Verktyg för datamanipuleringsspråk (DML) i SQL MCP Server

SQL Model Context Protocol (MCP) Server exponerar sju DML-verktyg (Data Manipulation Language) för AI-agenter. De här verktygen ger en typ av CRUD-yta för databasåtgärder – skapa, läsa, uppdatera och ta bort poster, aggregera data samt köra lagrade procedurer. Alla verktyg respekterar rollbaserad åtkomstkontroll (RBAC), entitetsbehörigheter och principer som definierats i konfigurationen.

Vad är DML-verktyg?

DML-verktyg (Data Manipulation Language) hanterar dataåtgärder: skapa, läsa, uppdatera och ta bort poster, aggregera data samt köra lagrade procedurer. Till skillnad från DDL (Data Definition Language) som ändrar schemat, fungerar DML uteslutande på dataplanet i befintliga tabeller och vyer.

De sju DML-verktygen är:

• describe_entities – Identifierar tillgängliga entiteter och åtgärder
• create_record – Infogar nya rader
• read_records – Ställer frågor till tabeller och vyer
• update_record – Ändrar befintliga rader
• delete_record – Tar bort rader
• execute_entity – Kör lagrade procedurer
• aggregate_records – Utför aggregeringsfrågor

När DML-verktyg aktiveras globalt och för en entitet exponerar SQL MCP Server dem via MCP-protokollet. Agenter interagerar aldrig direkt med ditt databasschema – de fungerar via abstraktionsskiktet för Data API Builder.

Verktygen

list_tools för svar

När en agent anropar list_toolsreturnerar 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" }
  ]
}

describe_entities

Returnerar de entiteter som är tillgängliga för den aktuella rollen. Varje post innehåller fältnamn, beskrivningar och tillåtna åtgärder. Det här verktyget frågar inte databasen. I stället läser den från den minnesinterna konfigurationen som skapats från konfigurationsfilen.

Parameters

Exempel på begäran

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

Exempelsvar

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

Skapar en ny rad i en tabell. Behörighet att skapa på entiteten krävs för den nuvarande rollen. Verktyget validerar indata mot entitetsschemat, tillämpar behörigheter på fältnivå, tillämpar skapa principer och returnerar den skapade posten med alla genererade värden.

Parameters

read_records

Utför en fråga på en tabell eller vy. Stöder filtrering, sortering, sidnumrering och fältval. Verktyget skapar deterministisk SQL från strukturerade parametrar, tillämpar läsbehörigheter och fältprojektioner och tillämpar säkerhetsprinciper på radnivå.

Parameters

Paginering-svar

När fler resultat är tillgängliga innehåller svaret en after markör. Skicka det här värdet som after parameter i nästa begäran för att hämta nästa sida.

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

Fältets närvaro anger att after det finns fler sidor. När after är frånvarande har du nått den sista sidan.

JOIN-åtgärder

Verktyget read_records är utformat för en enda tabell eller vy. Därför stöds inte JOIN-åtgärder i det här verktyget. Den här designen hjälper till att isolera ansvar, förbättra prestanda och begränsa effekten på sessionens kontextfönster.

Join-åtgärder är dock inte ett gränsfall, och Data API Builder (DAB) stöder redan avancerade frågor via GraphQL-slutpunkten. För mer komplexa frågor rekommenderar vi att du använder en vy i stället för en tabell. Du kan också använda execute_entity verktyget för att köra lagrade procedurer för att kapsla in parametriserade frågor.

update_record

Ändrar en befintlig rad. Kräver att primärnyckeln och fälten uppdateras. Verktyget verifierar att den primära nyckeln finns, framtvingar uppdateringsbehörigheter och principer och endast uppdaterar fält som den aktuella rollen kan ändra.

Parameters

delete_record

Tar bort en befintlig rad. Kräver en primärnyckel. Verktyget verifierar att den primära nyckeln finns, framtvingar borttagningsbehörigheter och principer och utför säker borttagning med transaktionsstöd.

Parameters

execute_entity

Kör en lagrad procedur. Stöder indataparametrar och utdataresultat. Verktyget validerar indataparametrar mot procedurens signatur, framtvingar körningsbehörigheter och skickar parametrar på ett säkert sätt.

Parameters

samla_poster

Utför aggregeringsfrågor i tabeller och vyer. Har stöd för vanliga mängdfunktioner som antal, summa, medelvärde, minimum och maximum. Verktyget skapar deterministisk SQL från strukturerade parametrar, tillämpar läsbehörigheter och fältprojektioner och tillämpar säkerhetsprinciper på radnivå.

Parameters

Exempel: räkna med groupby och ha

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

Verktyget aggregate-records kan konfigureras som ett booleskt objekt eller som ett objekt med fler inställningar:

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

Egenskapen query-timeout anger den maximala körningstiden i sekunder (intervall: 1–600). Den här inställningen hjälper till att förhindra att långvariga aggregeringsfrågor förbrukar överdrivna resurser.

Körningskonfiguration

Konfigurera DML-verktyg globalt i körningsavsnittet i :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
      }
    }
  }
}

Varje verktygsegenskap under runtime.mcp.dml-tools accepterar true eller false. Verktyget aggregate-records stöder också ett objektformat med enabled och 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
        }
      }
    }
  }
}

Om du vill aktivera eller inaktivera alla DML-verktyg samtidigt anger du "dml-tools" till true eller false.

Använda CLI

Ange egenskaper individuellt med hjälp av DATA API-builder 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

Inaktivera verktyg

När du inaktiverar ett verktyg på körningsnivå visas det aldrig för agenter, oavsett entitetsbehörighet eller rollkonfiguration. Den här inställningen är användbar när du behöver strikta driftsgränser.

Vanliga scenarier

• Inaktivera delete-record för att förhindra dataförlust i produktion
• Inaktivera create-record för skrivskyddade rapportslutpunkter
• Inaktivera execute-entity när lagrade procedurer inte används
• Inaktivera aggregate-records när aggregeringsfrågor inte behövs

När ett verktyg är inaktiverat globalt döljs verktyget från list_tools svaret och kan inte anropas.

Enhetsinställningar

Entiteter deltar automatiskt i MCP om du inte uttryckligen begränsar dem. Egenskapen mcp på en entitet styr dess MCP-deltagande. Använd objektformatet för explicit kontroll.

Objektformat

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

Om du inte anger mcp på en entitet aktiveras DML-verktyg som standard när MCP är aktiverat globalt.

Anpassade verktyg för lagrade procedurer

För entiteter med lagrad procedur använder du custom-tool egenskapen för att registrera proceduren som ett namngivet MCP-verktyg:

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

Omfång för kontroll per verktyg

Växlingar per verktyg konfigureras endast på den globala körningsnivån under runtime.mcp.dml-tools.

På entitetsnivå mcp är en boolesk grind eller ett objekt med dml-tools och custom-tool egenskaper.

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

Ett verktyg är endast tillgängligt om det är aktiverat globalt och entiteten tillåter DML-verktyg.

RBAC-integrering

Varje DML-verktygsåtgärd tillämpar dina rollbaserade åtkomstkontrollregler. En agents roll avgör vilka entiteter som är synliga, vilka åtgärder som tillåts, vilka fält som ingår och om policyer på radnivå gäller.

anonymous Om rollen endast tillåter läsbehörighet på Products:

• describe_entities visar endast read_records under funktioner
• create_record, update_recordoch delete_record är inte tillgängliga
• Endast fält som tillåts för anonymous visas i schemat

Konfigurera roller i :dab-config.json

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

Relaterat innehåll

• Översikt över SQL MCP Server
• Lägga till semantiska beskrivningar i SQL MCP Server
• Konfigurationsreferens för DATA API Builder (DAB)
• MCP-konfiguration på entitetsnivå
• Runtime MCP-konfiguration
• Distribuera SQL MCP Server till Azure Container Apps
• Nyheter i Data API Builder version 2.0