Trasporto STDIO per SQL MCP Server

SQL MCP Server supporta due trasporti: HTTP gestibile in streaming per scenari ospitati e cloud e stdio per lo sviluppo locale e l'integrazione dell'agente diretto. 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

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 dab-config.json 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 usare il trasporto stdio, abilitare MCP in dab-config.json:

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

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

Avvia in modalità stdio

Usare il --mcp-stdio flag su dab start:

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 role:<name> è posizionale e deve seguire --mcp-stdioimmediatamente . Se omesso, per impostazione predefinita il ruolo è anonymous. Il nome del ruolo deve corrispondere a un ruolo definito nella permissions sezione di almeno un'entità nella configurazione.

Funzionamento della modalità stdio

Quando --mcp-stdio 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 è impostato in modalità Simulator, indipendentemente dal file di configurazione. 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:

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 alla tua configurazione e alle autorizzazioni delle entità:

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

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 (mcp.json)

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

Salvare il file come .vscode/mcp.json 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 dab start separatamente in un terminale.

Claude Desktop (claude_desktop_config.json)

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

Combinare con altre dab start opzioni

--mcp-stdio è compatibile con tutte le altre dab start opzioni:

dab start \
  --mcp-stdio role:api-reader \
  --config ./dab-config.json \
  --LogLevel None

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 dab validate --config <path>
• La stringa di connessione del database è corretta e raggiungibile
• MCP è abilitato nella configurazione: "mcp": { "enabled": true }

Autorizzazione negata per le chiamate dello strumento MCP

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

Strumenti MCP non elencati

dml-tools è impostato su false a livello globale oppure l'entità ha "dml-tools": false nelle impostazioni di mcp. Verificare anche che mcp.enabled sia true.

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 --LogLevel per eliminare i messaggi di avvio dettagliati, se necessario.

Contenuti correlati

• dab start Informazioni di riferimento sul comando
• Panoramica di SQL MCP Server
• Quickstart: Usare SQL MCP Server con Visual Studio Code
• Configurare l'autenticazione per SQL MCP Server
• Strumenti di manipolazione dei dati