Strumenti DML (Data Manipulation Language) in SQL MCP Server

Il server MCP (SQL Model Context Protocol) espone sette 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, l'aggregazione dei dati 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, aggregazione dei dati e 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 sette 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
• aggregate_records - Esegue query di aggregazione

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" },
    { "name": "aggregate_records" }
  ]
}

descrivi_entità

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

Parametri

Richiesta di esempio

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

Risposta di esempio

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

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.

Parametri

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.

Parametri

Risposta di paginazione

Quando sono disponibili più risultati, la risposta include un after cursore. Passare questo valore come after parametro nella richiesta successiva per recuperare la pagina successiva.

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

La presenza del after campo indica che esistono più pagine. Quando after è assente, è stata raggiunta l'ultima pagina.

Operazioni JOIN

Lo read_records strumento è progettato per una singola tabella o vista. Di conseguenza, le operazioni JOIN non sono supportate in questo strumento. Questa progettazione consente di isolare responsabilità, migliorare le prestazioni e limitare l'impatto sulla finestra di contesto della sessione.

Tuttavia, le operazioni JOIN non sono un caso perimetrale e Il generatore di API dati (DAB) supporta già query sofisticate tramite l'endpoint GraphQL. Per query più complesse, è consigliabile usare una vista anziché una tabella. È anche possibile usare il execute_entity strumento per eseguire stored procedure per incapsulare query con parametri.

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.

Parametri

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.

Parametri

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.

Parametri

aggregate_records

Esegue query di aggregazione su tabelle e viste. Supporta funzioni di aggregazione comuni, ad esempio count, sum, average, minimum e maximum. 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.

Parametri

Esempio: conteggio con groupby e having

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

Lo aggregate-records strumento può essere configurato come valore booleano o come oggetto con altre impostazioni:

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

La query-timeout proprietà specifica il tempo di esecuzione massimo in secondi (intervallo: 1-600). Questa impostazione consente di evitare che le query di aggregazione a esecuzione prolungata consumino risorse eccessive.

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,
        "aggregate-records": true
      }
    }
  }
}

Ogni proprietà dello strumento in runtime.mcp.dml-tools accetta true o false. Lo aggregate-records strumento supporta anche un formato di oggetto con enabled e 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
        }
      }
    }
  }
}

Per abilitare o disabilitare tutti gli strumenti DML contemporaneamente, impostare su "dml-tools"true o false.

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
dab configure --runtime.mcp.dml-tools.aggregate-records.enabled true
dab configure --runtime.mcp.dml-tools.aggregate-records.query-timeout 30

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
• Disabilitare aggregate-records quando le query di aggregazione non sono necessarie

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 proprietà mcp di un'entità ne controlla la partecipazione MCP. Usare il formato dell'oggetto per il controllo esplicito.

Formato oggetto

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

Se non si specifica mcp in un'entità, per impostazione predefinita gli strumenti DML sono abilitati quando MCP è abilitato a livello globale.

Strumenti personalizzati per procedure memorizzate

Per le entità stored procedure, usare la custom-tool proprietà per registrare la routine come strumento MCP denominato:

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

Ambito del controllo per strumento

Le opzioni per ogni strumento vengono configurate solo a livello di esecuzione globale in runtime.mcp.dml-tools.

A livello di entità, mcp è una porta booleana o un oggetto con le proprietà dml-tools e 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
      }
    }
  }
}

Uno strumento è disponibile solo se abilitato a livello globale e l'entità consente strumenti DML.

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": [
            {
              "action": "*"
            }
          ]
        }
      ]
    }
  }
}

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)
• Configurazione MCP a livello di entità
• Configurazione MCP runtime
• Deploy SQL MCP Server su Azure Container Apps
• Novità di Data API Builder versione 2.0