Udostępnij za pośrednictwem

Transport Stdio dla programu SQL MCP Server

Ważna

Serwer MCP (SQL Model Context Protocol) jest dostępny w narzędziu Data API Builder w wersji 1.7 lub nowszej.

Program SQL MCP Server obsługuje dwa transporty: HTTP strumieniowy dla scenariuszy hostowanych i w chmurze oraz stdio na potrzeby lokalnego rozwoju i bezpośredniej integracji agenta. W tym artykule omówiono transport stdio.

W trybie stdio konstruktor interfejsu API danych (DAB) komunikuje się z klientem MCP w całości za pośrednictwem standardowego wejścia/wyjścia (stdin/stdout). Nie uruchomiono serwera HTTP ani portu sieciowego. Klient MCP uruchamia DAB jako proces podrzędny i przesyła komunikaty w obie strony przy użyciu protokołu MCP (Model Context Protocol).

Kiedy używać transportu stdio

Scenario Zalecany transport
Programowanie lokalne na stacji roboczej dewelopera Stdio
Program VS Code z GitHub Copilot (w trybie agenta) Stdio
Potoki CI/CD (ciągłej integracji/ciągłego wdrażania) lub automatyzacja za pomocą agenta skryptowego Stdio
Hosting w chmurze (Container Apps, App Service) HTTP
Agent AI Foundry z zdalnym punktem końcowym MCP HTTP
Zespoły agentów dzielące ten sam punkt końcowy HTTP

Wybierz stdio, jeśli chcesz najprostszą konfigurację lokalną bez otwartych portów. Wybierz pozycję HTTP, gdy serwer MCP musi być dostępny w sieci.

Wymagania wstępne

  • Zainstalowano CLI narzędzia Data API Builder (wersja 1.7 lub nowsza)
  • Istniejący dab-config.json z włączonym programem MCP (zobacz Wymagana konfiguracja)
  • Klient zgodny z programem MCP (program VS Code z GitHub Copilot, Claude Desktop lub agent niestandardowy)

Wymagana konfiguracja

Przed rozpoczęciem korzystania z transportu stdio, włącz MCP w dab-config.json.

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

Pole path jest używane tylko do transportu HTTP i jest ignorowane w trybie stdio. Blok dml-tools steruje operacjami manipulowania danymi dostępnymi jako narzędzia MCP.

Ważna

Jeśli brakuje "mcp": { "enabled": false } lub bloku mcp, usługa DAB nie może uruchomić się w trybie stdio.

Uruchamianie w trybie stdio

Użyj flagi --mcp-stdio w :dab start

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

Aby uruchomić pod określoną rolą uprawnień:

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

Argument role:<name> jest pozycyjny i musi natychmiast postępować zgodnie z .--mcp-stdio W przypadku pominięcia rola jest domyślnie ustawiona na anonymous. Nazwa roli musi być zgodna z rolą zdefiniowaną w permissions sekcji co najmniej jednej jednostki w konfiguracji.

Jak działa tryb stdio

Po wykryciu --mcp-stdio DAB wprowadza następujące zmiany wewnętrzne:

Kodowanie UTF-8 (bez znacznika kolejności bajtów)

Dane wejściowe i wyjściowe konsoli są wymuszane do formatu UTF-8 bez znaku kolejności bajtów (BOM). To ustawienie UTF-8 jest wymagane do czystej komunikacji JSON przez stdio, ponieważ wielu klientów MCP odrzuca strumienie z prefiksem BOM.

Uwierzytelnianie symulatora

Dostawca uwierzytelniania jest ustawiony na tryb symulatora, niezależnie od tego, co jest określone w pliku konfiguracji. Ten tryb symulatora umożliwia bezpośrednie zastosowanie określonej roli bez rzeczywistego tokenu internetowego JSON (JWT) lub dostawcy tożsamości. Dostawca symulatora jest przeznaczony dla scenariuszy programowania i nie powinien być używany do zabezpieczania produkcyjnych punktów końcowych HTTP — ale jest dokładnie odpowiedni dla lokalnych sesji stdio.

Następujące wartości są stosowane w pamięci i przesłaniają konfigurację podczas sesji:

Klucz Wartość
MCP:StdioMode "true"
MCP:Role "<role-name>" lub "anonymous"
Runtime:Host:Authentication:Provider "Simulator"

Brak odbiornika HTTP

Host ASP.NET Core jest uruchamiany i wszystkie usługi są zarejestrowane, ale usługa DAB wywołuje stdio.RunAsync() zamiast host.Run(). Żaden port protokołu TCP (Transmission Control Protocol) nie jest powiązany. Wszystkie komunikaty protokołu MCP przepływają przez stdin/stdout.

Dostępne narzędzia MCP

Następujące narzędzia są dostępne w trybie stdio, w zależności od Twojej dml-tools konfiguracji oraz uprawnień jednostki:

Narzędzie Opis
describe_entities Wyświetla listę dostępnych jednostek oraz ich pól i uprawnień
create_record Wstawia nowy rekord (tylko tabele)
read_records Odczytuje rekordy z jednostki
update_record Aktualizuje istniejący rekord
delete_record Usuwa istniejący rekord (tabele i widoki)
execute_entity Wykonuje jednostkę procedury składowanej

Niestandardowe narzędzia MCP wspierane przez procedury składowane są również rejestrowane podczas korzystania z programu --mcp-stdio.

Konfigurowanie klienta MCP dla programu stdio

Klienci MCP, którzy obsługują transport stdio, uruchamiają DAB jako podproces i przekierowują jego wejście/wyjście (stdin/stdout). Składnia konfiguracji klienta różni się w zależności od 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", "none"
      ]
    }
  }
}

Zapisz ten plik w .vscode/mcp.json folderze projektu. Program VS Code automatycznie wykrywa konfigurację i wyświetla serwer w programie MCP: Lista serwerów. Ponieważ klient zarządza cyklem życia procesu, nie trzeba uruchamiać dab start go oddzielnie w terminalu.

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

Połącz z innymi dab start opcjami

--mcp-stdio jest zgodny ze wszystkimi innymi dab start opcjami:

Option Zachowanie za pomocą polecenia --mcp-stdio
--config Używa określonego pliku konfiguracji (tak samo jak w trybie HTTP)
--LogLevel Stosuje określony poziom logowania (none: zalecany dla stdio) 
dab start \
  --mcp-stdio role:api-reader \
  --config ./dab-config.json \
  --LogLevel None

Rozwiązywanie problemów z trybem stdio

Failed to start the engine in MCP stdio mode.

Nie można uruchomić narzędzia DAB. Upewnij się, że:

  • Plik konfiguracji jest prawidłowy: uruchom dab validate --config <path>
  • Twoje dane połączeniowe bazy danych są poprawne i osiągalne
  • MCP jest włączone w twojej konfiguracji: "mcp": { "enabled": true }

Odmowa uprawnień w wywołaniach narzędzi MCP

Rola określona przez role:<name> nie ma wymaganych uprawnień dla jednostki i operacji. Sprawdź sekcję permissions odpowiedniej jednostki w konfiguracji.

Narzędzia MCP, których nie ma na liście

Wartość dml-tools jest ustawiona na false globalnie, albo jednostka ma "dml-tools": false w ustawieniach mcp. Sprawdź również, czy mcp.enabled jest to true.

Błędne lub zniekształcone dane wyjściowe albo błędy analizowania JSON

Przed uruchomieniem serwera MCP upewnij się, że kod startowy nie zapisuje tekstu innego niż JSON do stdout. Wyjście dziennika powinno trafiać do stderr lub do pliku dziennika, zamiast do stdout. Użyj polecenia --LogLevel, aby pominąć szczegółowe komunikaty uruchamiania w razie potrzeby.

Treści powiązane

  • Last updated on