Stdio přenos pro SQL MCP Server

Důležité

Server PROTOKOLU MCP (SQL Model Context Protocol) je k dispozici v Tvůrci rozhraní Data API verze 1.7 a novější.

SQL MCP Server podporuje dva přenosy: streamovatelné HTTP pro hostované a cloudové scénáře a stdio pro místní vývoj a přímou integraci agenta. Tento článek se zabývá dopravou stdio .

V stdio režimu tvůrce rozhraní DATA API (DAB) komunikuje s klientem MCP zcela přes standardní vstup a výstup (stdin/stdout). Není spuštěn žádný server HTTP ani síťový port. Klient MCP spouští DAB jako podřízený proces a kanáluje zprávy zpět pomocí protokolu MCP (Model Context Protocol).

Kdy použít stdio dopravu

Scénář Doporučená doprava
Místní vývoj na vývojářské pracovní stanici stdio
VS Code s GitHub Copilot (režim agenta) stdio
Automatizace kanálů CI/CD nebo skriptovaných agentů stdio
Hostování cloudu (Container Apps, App Service) HTTP
Agent Foundry AI s vzdáleným koncovým bodem MCP HTTP
Týmy agentů sdílejí stejný koncový bod HTTP

Zvolte stdio , kdy chcete nejjednodušší možnou místní instalaci bez otevřených portů. Zvolte HTTP, když je potřeba, aby byl server MCP dostupný přes síť.

Předpoklady

  • Nainstalované CLI pro Data API builder (verze 1.7 nebo novější)
  • Existující dab-config.json s povolenou službou MCP (viz Požadovaná konfigurace)
  • Klient kompatibilní s MCP (VS Code s GitHub Copilot, Claude Desktopem nebo vlastním agentem)

Požadovaná konfigurace

Před použitím stdio přenosu povolte MCP ve vašem 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
    }
  }
}

Pole path se používá pouze pro přenos HTTP a ignoruje se v režimu stdio. Blok dml-tools řídí, které operace manipulace s daty jsou k dispozici jako nástroje MCP.

Důležité

Pokud chybí blok "mcp": { "enabled": false } nebo mcp, DAB se nespustí v stdio režimu.

Spuštění v stdio režimu

Použijte příznak --mcp-stdio na dab start

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

Aby bylo možné spustit pod specifickou rolí oprávnění:

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

Argument role:<name> je poziční a musí okamžitě následovat --mcp-stdio. Pokud tento parametr vynecháte, role se ve výchozím nastavení nastaví na anonymous. Název role se musí shodovat s rolí definovanou v oddílu permissions nejméně jedné entity v konfiguraci.

Jak stdio funguje režim

Když je --mcp-stdio detekováno, DAB interně provede následující změny:

Kódování UTF-8 (bez značky pořadí bajtů)

Vstup a výstup konzoly jsou nastaveny na UTF-8 bez označení pořadí bajtů (BOM). Toto nastavení UTF-8 je vyžadováno pro čistou JSON-over-stdio komunikaci, protože mnoho klientů MCP odmítá datové proudy s předponou BOM.

Ověřování simulátoru

Zprostředkovatel ověřování se přepíše do režimu simulátoru bez ohledu na to, co váš konfigurační soubor určuje. Tento režim simulátoru umožňuje použít zadanou roli přímo bez skutečného webového tokenu JSON (JWT) nebo zprostředkovatele identity. Poskytovatel simulátoru je navržen pro vývojové scénáře a neměl by se používat k zabezpečení produkčních HTTP koncových bodů, ale je ideální pro místní stdio relace.

Následující hodnoty jsou aplikovány v paměti a přepisují vaši konfiguraci po dobu trvání relace.

Klíč Hodnota
MCP:StdioMode "true"
MCP:Role "<role-name>" nebo "anonymous"
Runtime:Host:Authentication:Provider "Simulator"

Žádný HTTP listener

Hostitel ASP.NET Core se spustí a všechny služby jsou zaregistrované, ale DAB volá stdio.RunAsync() místo host.Run(). Není vázán žádný port TCP (Transmission Control Protocol). Všechny zprávy protokolu MCP procházejí stdin/stdout.

Dostupné nástroje MCP

V režimu stdio jsou k dispozici následující nástroje, které podléhají vaší dml-tools konfiguraci a oprávnění entit:

nástroj Description
describe_entities Seznam dostupných entit a jejich polí a oprávnění
create_record Vloží nový záznam (pouze tabulky).
read_records Čte záznamy z entity.
update_record Aktualizuje existující záznam.
delete_record Odstraní existující záznam (tabulky a zobrazení).
execute_entity Spustí entitu uložené procedury.
aggregate_records Provádí agregační dotazy na tabulky a zobrazení.

Vlastní nástroje MCP zálohované uloženými procedurami jsou také registrovány při použití --mcp-stdio.

Konfigurace klienta MCP pro stdio

Klienti MCP, kteří podporují stdio přenos, spustí DAB jako podproces a přesměrují jeho stdin/stdout. Syntaxe konfigurace klienta se liší podle klienta.

VS Code (mcp.json)

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

Uložte tento soubor jako .vscode/mcp.json do složky projektu. VS Code rozpozná konfiguraci automaticky a zobrazí server v MCP: Seznam serverů. Vzhledem k tomu, že klient spravuje životní cyklus procesu, nemusíte v terminálu spouštět dab start samostatně.

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", "error"
      ]
    }
  }
}

Kombinování s dalšími dab start možnostmi

--mcp-stdio je kompatibilní se všemi ostatními dab start možnostmi:

Možnost Chování s --mcp-stdio
--config Používá zadaný konfigurační soubor (stejný jako režim HTTP).
--LogLevel Použije zadanou úroveň protokolu (errordoporučeno pro stdio) 
dab start \
  --mcp-stdio role:api-reader \
  --config ./dab-config.json \
  --LogLevel Error

Režim řešení potíží stdio

Failed to start the engine in MCP stdio mode

DAB se nepodařilo spustit. Zkontrolujte, že:

  • Konfigurační soubor je platný: spusťte dab validate --config <path>
  • Váš databázový připojovací řetězec je správný a dosažitelný.
  • McP je ve vaší konfiguraci povolený: "mcp": { "enabled": true }

Odepřeno oprávnění při volání nástroje MCP

Role zadaná uživatelem role:<name> nemá požadovaná oprávnění pro entitu a operaci. Zkontrolujte část permissions příslušné entity ve vaší konfiguraci.

Nástroje MCP nejsou uvedené v seznamu

Buď je dml-tools nastavená globálně false, nebo entita má "dml-tools": false ve svém nastavení mcp. Také ověřte, že mcp.enabled je true.

Zkomolený výstup nebo chyby analýzy JSON

Před spuštěním serveru MCP zajistěte, že ve spouštěcím kódu není nic, co by zapisovalo text bez formátu JSON do stdoutu. Výstup záznamu by měl jít na stderr nebo do souboru se záznamem, ne na stdout. V případě potřeby použijte --LogLevel pro potlačení podrobných spouštěcích zpráv.

Související obsah

  • Last updated on