Che cos'è 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 offre agli sviluppatori un modo semplice, prevedibile e sicuro per inserire gli agenti di intelligenza artificiale nei flussi di lavoro dei dati. A tale scopo, senza esporre il database o basarsi sull'analisi fragile del linguaggio naturale. Basandosi sull'astrazione delle entità del generatore di API dati, sul controllo degli accessi in base al ruolo, sulla memorizzazione nella cache e sulla telemetria, SQL MCP Server offre una piattaforma pronta per la produzione che funziona alla stessa maniera in REST, GraphQL e MCP. La configurazione viene eseguita una sola volta e il motore gestisce il resto.

Model Context Protocol (MCP)

Model Context Protocol (MCP) è uno standard che definisce il modo in cui gli agenti di intelligenza artificiale individuano e chiamano strumenti esterni. Uno strumento è una singola operazione, ad esempio la creazione di un record o la lettura di dati. Ogni strumento descrive gli input, gli output e il comportamento. MCP offre agli agenti un modo prevedibile per individuare e usare le funzionalità.

Server MCP per SQL

SQL MCP Server è il motore dinamico e open source di Microsoft per le app agenti. È possibile configurarlo con un file JSON che definisce:

• Come connettersi al database
• Tabelle, viste o stored procedure da esporre
• Autorizzazioni applicabili a ogni oggetto

SQL MCP Server è incluso come parte di Data API Builder (DAB) a partire dalla versione 1.7. Espone le operazioni SQL come una piccola famiglia di strumenti MCP in modo che gli agenti possano interagire con le entità di database tramite un contratto controllato. Il server è self-hosted, ma, per gli sviluppatori, può anche essere eseguito localmente tramite la riga di comando DAB.

Suggerimento

Il generatore di API dati è open source e gratuito da usare.

Casi d'uso

Ecco alcuni casi d'uso tipici per SQL MCP Server:

• Consentire ai copiloti o ai chatbot di eseguire operazioni CRUD sicure
• Creare automazione interne senza scrivere SQL
• Aggiungere funzionalità dell'agente senza esporre direttamente il database

Protezione dello schema

Il generatore di API dati usa un livello di astrazione di entità ben definito che elenca tutte le tabelle, le viste e le stored procedure esposte tramite l'API nella configurazione. Questo livello consente di assegnare nomi e colonne alias, descrivere oggetti e parametri e limitare i campi disponibili per ruoli diversi.

Importante

Il generatore di API dati (DAB) è consapevole del ruolo ed espone solo le entità e le operazioni a cui il ruolo corrente è autorizzato ad accedere.

Poiché SQL MCP Server è una funzionalità di Generatore API dati, usa anche questo livello di astrazione. Questo approccio impedisce l'esposizione dello schema interno agli utenti esterni e consente di definire famiglie complesse di oggetti e relazioni, anche tra origini dati diverse, a livello di API.

Risoluzione di NL2SQL

SQL MCP Server adotta un approccio diverso rispetto a molti dei server MCP di database a breve vista attualmente disponibili. Un esempio chiave è che noi intenzionalmente non supportiamo NL2SQL.

Why? I modelli non sono deterministici e le query complesse sono le più probabili per produrre errori sottili. Queste query complesse sono spesso quelle che gli utenti sperano che l'IA possa generare, ma sono anche quelle che richiedono il maggior controllo quando vengono prodotte in modo non deterministico.

Annotazioni

Deterministico indica che lo stesso input produce sempre lo stesso output. Non esiste alcuna casualità o variazione tra le chiamate, che rende i risultati prevedibili, testabili e sicuri da automatizzare.

SQL MCP Server supporta invece ciò che potrebbe essere chiamato modello NL2DAB. Questo approccio usa il livello di astrazione dell'entità del generatore di API dati sicuro e il generatore di query DAB predefinito. Insieme, producono T-SQL (Transact-SQL) accurati e ben formati in modo completamente deterministico. Questo approccio rimuove il rischio, il sovraccarico e l'insensibilità associati a NL2SQL mantenendo al tempo stesso la sicurezza e l'affidabilità per le query generate dall'agente.

Supporto per DDL

DDL (Data Definition Language) è il linguaggio di database usato per creare e modificare oggetti come tabelle e viste. SQL MCP Server è basato su DML (Data Manipulation Language), il linguaggio di database usato per creare, leggere, aggiornare ed eliminare dati in tabelle e viste esistenti. DML illustra anche l'esecuzione delle stored procedure. Di conseguenza, SQL MCP Server è progettato per funzionare con i dati, non con lo schema. Questa progettazione è allineata ai casi d'uso MCP di produzione in cui gli agenti di intelligenza artificiale interagiscono con sistemi mission-critical o sensibili agli affari aziendali.

Suggerimento

Per modificare lo schema durante lo sviluppo locale, i tecnici possono usare l'estensione MSSQL in Visual Studio Code (VS Code), che offre supporto DDL completo.

Supporto per il controllo degli accessi in base al ruolo (RBAC)

SQL MCP Server trae vantaggio dallo stesso sistema di controllo degli accessi in base al ruolo (RBAC) collaudato usato in Generatore API dati. Ogni entità nella configurazione definisce i ruoli che possono leggere, creare, aggiornare o eliminare dati e quali campi sono inclusi o esclusi per tali ruoli. Queste regole si applicano automaticamente a ogni strumento MCP, assicurando che la sicurezza rimanga coerente tra REST, GraphQL e MCP senza alcuna configurazione aggiuntiva necessaria.

Importante

I vincoli basati sui ruoli si applicano a ogni passaggio dell'interazione dell'agente.

Supporto per la memorizzazione nella cache

SQL MCP Server memorizza automaticamente nella cache i risultati dello read_records strumento. La memorizzazione nella cache nel generatore di API dati è abilitata a livello globale ed è possibile configurarla per entità. La memorizzazione nella cache di livello 1 e 2 consente di ridurre il carico del database, impedire le stampe delle richieste e supportare scenari warm-start in ambienti con scalabilità orizzontale.

Supporto per il monitoraggio

SQL MCP Server genera log e dati di telemetria che consentono alle aziende di monitorare e convalidare l'attività da un singolo riquadro di vetro. Questa funzionalità include Log Analytics di Azure, Application Insights e log di file locali all'interno di un contenitore.

Telemetria

SQL MCP Server è completamente strumentato con intervalli e attività OpenTelemetry (OTEL). Ogni operazione viene tracciata in modo che gli sviluppatori possano correlare il comportamento tra sistemi distribuiti. Altre informazioni sul supporto nativo di Open Telemetry del generatore di API dati.

Controlli di salute

SQL MCP Server fornisce controlli dettagliati sull'integrità e sulle entità tra gli endpoint REST, GraphQL e MCP. Salute del costruttore di API Dati consente agli sviluppatori di definire aspettative sulle prestazioni, impostare soglie e verificare che ogni endpoint funzioni come previsto.

Come configurare SQL MCP Server?

MCP è configurato nel file di configurazione DAB. Se si dispone già di una configurazione di Generatore API dati funzionante, l'aggiornamento alla versione 1.7 o successiva offre automaticamente un server MCP SQL funzionante senza passaggi aggiuntivi necessari.

Configurazione

È possibile abilitare MCP a livello globale o a livello di entità. Questa funzionalità consente di scegliere quali entità mostrano strumenti MCP e quali rimangono inaccessibili agli agenti. MCP segue le stesse regole usate per REST e GraphQL, quindi la configurazione rimane l'unica origine di verità per autorizzazioni, proiezioni e criteri.

Quando MCP è abilitato, SQL MCP Server genera automaticamente la superficie degli strumenti in base alla configurazione. Gli strumenti MCP non vengono definiti manualmente. Il sistema predefinito dml-tools individua ed espone le entità in modo procedurale, che viene ridimensionato in modo ottimale da schemi di piccole dimensioni a database di dimensioni molto grandi.

Get started

Iniziare significa creare l'oggetto dab-config.json per controllare il motore. È possibile eseguire questa attività manualmente oppure usare l'interfaccia della riga di comando di Data API Builder (DAB). L'interfaccia della riga di comando semplifica l'attività, consentendo di inizializzare il file con un singolo comando. I valori delle proprietà di configurazione possono usare stringhe letterali, variabili di ambiente o segreti di Azure Key Vault .

dab init --database-type mssql --connection-string "<your-connection-string>" --config dab-config.json --host-mode development

È possibile specificare ogni tabella, vista o stored procedure che si desidera che il SQL MCP Server esponga, aggiungendole alla configurazione. L'interfaccia della riga di comando consente di aggiungerli facilmente, assegnare alias, configurare le relative autorizzazioni e mappare le colonne, se necessario. Soprattutto, con la description proprietà è possibile includere dettagli semantici per aiutare i modelli linguistici a comprendere meglio i dati.

dab add {entity-name} \                          # object alias (Employees)
  --source {table-or-view-name} \                # database object (dbo.Employees)
  --source.type {table|view|stored-procedure} \  # object type (table)
  --permissions "{role:actions}" \               # role and allowed actions (anonymous:*)
  --description "{text}"                         # semantic description (Company employee records)

Impostazioni di runtime

Sql MCP Server è abilitato per impostazione predefinita nella configurazione del generatore di API dati. Nella maggior parte dei casi, non è necessario aggiungere impostazioni. Il server segue automaticamente le stesse autorizzazioni e regole di sicurezza dell'API e del database. Configurare MCP solo quando si vuole restringere o limitare le operazioni che gli agenti possono eseguire.

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

L'interfaccia della riga di comando consente anche di impostare ogni proprietà singolarmente o a livello di codice tramite scripting.

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

Perché disabilitare singoli strumenti?

Gli sviluppatori possono voler limitare azioni specifiche anche quando i ruoli o le autorizzazioni delle entità le consentono. La disabilitazione di uno strumento a livello di runtime garantisce che non venga mai visualizzata agli agenti. Ad esempio, la disattivazione delete_record nasconde completamente la funzionalità di eliminazione, indipendentemente dalla configurazione altrove. Questo scenario è insolito ma utile quando sono necessari limiti operativi rigorosi.

Impostazioni entità

Non è inoltre necessario abilitare MCP in ogni entità. Le entità partecipano automaticamente a meno che non si scelga di limitarle. 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. Le impostazioni predefinite gestiscono tutti gli elementi.

"entities": {
  "products": {
    "mcp": {
      "dml-tools": true
    }
  }
}

Strumenti DML

SQL MCP Server espone sei strumenti DML (Data Manipulation Language) che consentono agli agenti di intelligenza artificiale di eseguire operazioni di database sicure e indipendenti dai tipi: describe_entities, create_recordread_records, update_record, , delete_recorde execute_entity. Questi strumenti costituiscono una superficie CRUD prevedibile che riflette sempre la configurazione, le autorizzazioni e lo schema.

Ogni strumento rispetta il controllo degli accessi in base al ruolo, le autorizzazioni delle entità e i criteri. Gli agenti non interagiscono mai direttamente con il database. Funzionano tramite il livello di astrazione di Generatore API dati sicuro.

Per informazioni dettagliate su ogni strumento, opzioni di configurazione e procedure consigliate, vedere Informazioni di riferimento sugli strumenti DML.

Contenuti correlati

• Aggiunta di descrizioni semantiche al server SQL MCP
• Strumenti di manipolazione dei dati in SQL MCP Server
• Distribuire SQL MCP Server su Azure Container Apps