Strumenti DML (Data Manipulation Language) in SQL MCP Server

Importante

SQL MCP Server è disponibile in anteprima e questa documentazione e l'implementazione del motore è soggetta a modifiche durante questo periodo di valutazione.

SQL MCP Server espone sei strumenti DML (Data Manipulation Language) agli agenti di intelligenza artificiale. Questi strumenti forniscono una superficie CRUD tipizzata per le operazioni di database, ovvero la creazione, la lettura, l'aggiornamento e l'eliminazione di record e l'esecuzione di stored procedure. Tutti gli strumenti rispettano il controllo degli accessi in base al ruolo, le autorizzazioni delle entità e i criteri definiti nella configurazione.

Che cosa sono gli strumenti DML?

Gli strumenti DML (Data Manipulation Language) gestiscono le operazioni dei dati: creazione, lettura, aggiornamento ed eliminazione di record, oltre all'esecuzione di stored procedure. A differenza di DDL (Data Definition Language) che modifica lo schema, DML funziona esclusivamente sul piano dati in tabelle e viste esistenti.

I sei strumenti DML sono:

• describe_entities - Individua le entità e le operazioni disponibili
• create_record - Inserisce nuove righe
• read_records - Interroga tabelle e viste
• update_record - Modifica le righe esistenti
• delete_record - Rimuove le righe
• execute_entity - Esegue procedure memorizzate

Quando gli strumenti DML sono abilitati a livello globale e per un'entità, SQL MCP Server li espone tramite il protocollo MCP. Gli agenti non interagiscono mai direttamente con lo schema del database. Funzionano tramite il livello di astrazione del generatore di API dati.

Strumenti

list_tools risposta

Quando un agente chiama list_tools, SQL MCP Server restituisce:

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

descrivi_entità

Restituisce le entità disponibili per il ruolo corrente. Ogni voce include nomi di campo, tipi di dati, chiavi primarie e operazioni consentite. Questo strumento non esegue query sul database. Invece, legge dalla configurazione in memoria creata dal file di configurazione.

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

Annotazioni

Le opzioni di entità usate da uno qualsiasi degli strumenti CRUD o degli strumenti di esecuzione DML derivano direttamente da describe_entities. La descrizione semantica interna associata a ogni strumento applica questo flusso in due passaggi.

create_record

Crea una nuova riga in una tabella. È richiesta l'autorizzazione di creazione sull'entità per il ruolo corrente. Lo strumento convalida l'input sullo schema dell'entità, applica le autorizzazioni a livello di campo, applica i criteri di creazione e restituisce il record creato con tutti i valori generati.

read_records

Esegue una query su una tabella o una vista. Supporta il filtro, l'ordinamento, la paginazione e la selezione dei campi. Lo strumento compila SQL deterministico da parametri strutturati, applica autorizzazioni di lettura e proiezioni di campo e applica criteri di sicurezza a livello di riga.

I risultati di read_records vengono memorizzati automaticamente nella cache usando il sistema di memorizzazione nella cache di Data API Builder. È possibile configurare la durata (TTL) della cache a livello globale o per entità per ridurre il carico del database.

update_record

Modifica una riga esistente. Richiede l'aggiornamento della chiave primaria e dei campi. Lo strumento convalida l'esistenza della chiave primaria, applica le autorizzazioni di aggiornamento e i criteri e aggiorna solo i campi che il ruolo corrente può modificare.

delete_record

Rimuove una riga esistente. Richiede la chiave primaria. Lo strumento convalida l'esistenza della chiave primaria, applica autorizzazioni e criteri di eliminazione ed esegue l'eliminazione sicura con il supporto delle transazioni.

Avvertimento

Alcuni scenari di produzione disabiliteranno questo strumento a livello globale per vincolare i modelli su larga scala.

execute_entity

Esegue una procedura memorizzata. Supporta parametri di input e risultati di output. Lo strumento convalida i parametri di input rispetto alla firma della procedura, applica le autorizzazioni di esecuzione e passa i parametri in modo sicuro.

Configurazione del runtime

Configurare gli strumenti DML a livello globale nella sezione runtime di 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
      }
    }
  }
}

Uso dell'CLI

Impostare le proprietà singolarmente usando l'interfaccia della riga di comando di Generatore API dati:

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

Disabilitazione degli strumenti

Quando si disabilita uno strumento a livello di runtime, non viene mai visualizzato dagli agenti, indipendentemente dalle autorizzazioni dell'entità o dalla configurazione del ruolo. Questa impostazione è utile quando sono necessari limiti operativi rigorosi.

Scenari comuni

• Disabilitare delete-record per evitare la perdita di dati nell'ambiente di produzione
• Disabilitare create-record per gli endpoint di report di sola lettura
• Disabilitare execute-entity quando le stored procedure non sono utilizzate

Quando uno strumento è disabilitato a livello globale, lo strumento viene nascosto dalla list_tools risposta e non può essere richiamato.

Impostazioni entità

Le entità partecipano automaticamente a MCP, a meno che non venga esplicitamente applicata una restrizione. La dml-tools proprietà esiste in modo da poter escludere un'entità da MCP o restringerne le funzionalità, ma non è necessario impostare nulla per l'uso normale.

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

Se non si specifica mcp.dml-tools in un'entità, l'impostazione predefinita è true quando MCP è abilitato a livello globale.

Controllo con granularità fine

È possibile disabilitare strumenti specifici per singole entità:

{
  "entities": {
    "AuditLogs": {
      "mcp": {
        "dml-tools": {
          "create-record": true,
          "read-records": true,
          "update-record": false,
          "delete-record": false
        }
      }
    }
  }
}

Questa configurazione consente agli agenti di creare e leggere i log di controllo, ma impedisce la modifica o l'eliminazione.

Integrazione RBAC (controllo degli accessi in base al ruolo)

Ogni operazione dello strumento DML applica le regole di controllo degli accessi in base al ruolo. Il ruolo di un agente determina quali entità sono visibili, quali operazioni sono consentite, quali campi sono inclusi e se si applicano criteri a livello di riga.

Se il ruolo consente solo l'autorizzazione anonymous di lettura per Products:

• describe_entities mostra read_records solo nelle operazioni
• create_record, update_recorde delete_record non sono disponibili
• Solo i campi consentiti per anonymous vengono visualizzati nello schema

Configura i ruoli in dab-config.json:

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

Contenuti correlati

• Panoramica di SQL MCP Server
• Aggiunta di descrizioni semantiche al server SQL MCP
• Informazioni di riferimento sulla configurazione di Generatore API dati (DAB)
• Distribuire SQL MCP Server su Azure Container Apps