Condividi tramite

Trasporto STDIO per SQL MCP Server

Importante

Il server MCP (SQL Model Context Protocol) è disponibile in Generatore API dati versione 1.7 e successive.

SQL MCP Server supporta due tipi di trasporto: HTTP streamable per scenari ospitati e cloud, e std per lo sviluppo locale e l'integrazione diretta dell'agente. Questo articolo illustra il trasporto stdio.

In modalità stdio, il generatore di API dati (DAB) comunica con un client MCP interamente su input/output standard (stdin/stdout). Non viene avviato alcun server HTTP o porta di rete. Il client MCP avvia DAB come processo figlio e invia messaggi avanti e indietro usando il protocollo MCP (Model Context Protocol).

Quando usare il trasporto stdio

Scenario Trasporto consigliato
Sviluppo locale in una workstation per sviluppatori stdio
VS Code con GitHub Copilot (modalità agente) stdio
Pipeline CI/CD o automazione degli agenti con script stdio
Hosting cloud (app contenitore, servizio app) HTTP
Agente di AI Foundry con endpoint MCP remoto HTTP
Team di agenti che condividono lo stesso endpoint HTTP

Scegliere stdio quando si vuole la configurazione locale più semplice possibile senza porte aperte. Scegliere HTTP quando il server MCP deve essere raggiungibile attraverso una rete.

Prerequisiti

  • CLI Generatore Data API installata (versione 1.7 o successiva)
  • Esistente con MCP abilitato (vedere Configurazione necessaria)
  • Un client compatibile con MCP (VS Code con GitHub Copilot, Claude Desktop o un agente personalizzato)

Configurazione richiesta

Prima di utilizzare il trasporto standard di input/output (stdio), abilitare MCP in:

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

Il campo viene usato solo per il trasporto HTTP e viene ignorato in modalità stdio. Il blocco controlla quali operazioni di manipolazione dei dati sono disponibili come strumenti MCP.

Importante

Se uno dei due blocchi è mancante, DAB non viene avviato in modalità stdio.

Avvia in modalità stdio

Usare il flag in :

dab start --mcp-stdio --config ./dab-config.json

Eseguire con un ruolo di autorizzazione specifico:

dab start --mcp-stdio role:authenticated --config ./dab-config.json

L'argomento è posizionale e deve seguire immediatamente . Se omesso, per impostazione predefinita il ruolo è . Il nome del ruolo deve corrispondere a un ruolo definito nella sezione di almeno un'entità nella configurazione.

Funzionamento della modalità stdio

Quando viene rilevato, DAB apporta internamente le modifiche seguenti:

Codifica UTF-8 (senza marcatore di ordine dei byte)

L'input e l'output della console vengono forzati a UTF-8 senza un indicatore di ordine dei byte (BOM). Questa impostazione UTF-8 è necessaria per la comunicazione JSON-over-stdio pulita perché molti client MCP rifiutano flussi con prefisso BOM.

Autenticazione del simulatore

Il provider di autenticazione è sostituito in modalità simulatore, indipendentemente dal file di configurazione specificati. Questa modalità simulatore consente di applicare il ruolo specificato direttamente senza un vero token JSON Web (JWT) o un provider di identità. Il provider di simulatori è progettato per scenari di sviluppo e non deve essere usato per proteggere gli endpoint HTTP di produzione, ma è esattamente adatto per le sessioni stdio locali.

I valori seguenti vengono applicati in memoria ed eseguono l'override della configurazione durante la sessione:

Chiave Valore
MCP:StdioMode "true"
MCP:Role oppure
Runtime:Host:Authentication:Provider "Simulator"

Nessun listener HTTP

L'host ASP.NET Core viene avviato e tutti i servizi vengono registrati, ma DAB chiama stdio.RunAsync() anziché host.Run(). Non è associata alcuna porta TCP (Transmission Control Protocol). Tutti i messaggi del protocollo MCP passano attraverso stdin/stdout.

Strumenti MCP disponibili

Gli strumenti seguenti sono disponibili in modalità stdio, soggetti alle autorizzazioni di configurazione ed entità:

Strumento Descrizione
describe_entities Elenca le entità disponibili e i relativi campi e autorizzazioni
create_record Inserisce un nuovo record (solo tabelle)
read_records Legge i record da un'entità
update_record Aggiorna un record esistente
delete_record Elimina un record esistente (tabelle e viste)
execute_entity Esegue un'entità stored procedure

Anche gli strumenti MCP personalizzati supportati dalle stored procedure vengono registrati quando si usa .

Configurare un client MCP per stdio

I client MCP che supportano il trasporto stdio avviano DAB come subprocesso e indirizzano i suoi stdin/stdout. La sintassi di configurazione client varia in base al client.

VS Code ()

{
  "servers": {
    "sql-mcp-server": {
      "type": "stdio",
      "command": "dab",
      "args": [
        "start",
        "--mcp-stdio",
        "role:anonymous",
        "--config",
        "${workspaceFolder}/dab-config.json"
      ]
    }
  }
}

Salvare il file come all'interno della cartella del progetto. VS Code rileva automaticamente la configurazione e mostra il server in MCP: Elenca server. Poiché il client gestisce il ciclo di vita del processo, non è necessario eseguire separatamente in un terminale.

Claude Desktop ()

{
  "mcpServers": {
    "sql-mcp-server": {
      "command": "dab",
      "args": [
        "start",
        "--mcp-stdio",
        "role:anonymous",
        "--config",
        "/absolute/path/to/dab-config.json"
      ]
    }
  }
}

Combinare con altre opzioni

è compatibile con tutte le altre opzioni:

Opzione Comportamento con
--config Usa il file di configurazione specificato (uguale alla modalità HTTP)
--LogLevel Applica il livello di log specificato
--verbose Imposta il livello di log al livello Informazione
--no-https-redirect Accettato ma non ha alcun effetto—nessun server HTTP è in esecuzione 
dab start \
  --mcp-stdio role:api-reader \
  --config ./dab-config.json \
  --LogLevel Information

Risoluzione dei problemi della modalità stdio

Failed to start the engine in MCP stdio mode.

DAB non è riuscito ad avviarsi. Controllare che:

  • Il file di configurazione è valido: eseguire
  • La stringa di connessione del database è corretta e raggiungibile
  • MCP è abilitato nella configurazione:

Autorizzazione negata per le chiamate dello strumento MCP

Il ruolo specificato da non dispone delle autorizzazioni necessarie per l'entità e l'operazione. Controllare la sezione dell'entità pertinente nella configurazione.

Strumenti MCP non elencati

È impostato su globalmente oppure l'entità ha le relative impostazioni. Verificare anche che sia .

Errori di analisi JSON o output non chiaro

Assicurarsi che nulla nel codice di avvio scriva testo non JSON in stdout prima dell'avvio del server MCP. L'output del log dovrebbe essere indirizzato a stderr o a un file di registro, non su stdout. Usare per sopprimere i messaggi di avvio dettagliati, se necessario.

Contenuti correlati

  • Last updated on