Übersetzte Seite

Diese Seite wurde mit KI-Unterstützung aus dem Englischen übersetzt. Bei Abweichungen ist die englische Version maßgeblich.

mcp

Befehl zum Starten von StackQL als Model-Context-Protocol-Server (MCP-Server), mit dem KI-Agenten und Assistenten über die Abfragefunktionen von StackQL mit Cloud-Infrastruktur interagieren können.

Was ist MCP?

Das Model Context Protocol (MCP) ist ein offenes Protokoll, das standardisiert, wie KI-Anwendungen mit externen Datenquellen und Tools interagieren. Wenn Sie StackQL als MCP-Server ausführen, können KI-Agenten (Claude, Cursor, Continue, eigene Agenten usw.) Cloud-Infrastruktur über mehrere Provider hinweg in natürlicher Sprache abfragen und verwalten.

Syntax

stackql mcp [flags] für einen eigenständigen MCP-Server.

stackql srv [flags], um den MCP-Server zusammen mit dem PostgreSQL-Wire-Protokoll-Server im selben Prozess auszuführen.

Deployment-Modi

Der MCP-Server von StackQL kann in drei verschiedenen Konfigurationen bereitgestellt werden, um unterschiedlichen Architekturanforderungen gerecht zu werden. Die folgenden Beispiele aktivieren mit "allow_unauthenticated": true den unauthentifizierten Betrieb, der sich für die lokale Entwicklung eignet; für alles, was ein anderer Prozess oder Host erreichen kann, konfigurieren Sie stattdessen ein Bearer-Token (siehe HTTP-Client-Authentifizierung).

1. Eigenständiger MCP-Server

Führen Sie StackQL als dedizierten MCP-Server auf einem angegebenen Port aus.

stackql mcp \
  --mcp.server.type=http \
  --mcp.config '{"server": {"transport": "http", "address": "127.0.0.1:9912", "allow_unauthenticated": true}}'

Anwendungsfall: wenn Sie nur Zugriff über das MCP-Protokoll benötigen und keine Kompatibilität mit dem PostgreSQL-Wire-Protokoll brauchen.

2. MCP + PostgreSQL-Server (In-Memory)

Führen Sie MCP- und PostgreSQL-Server gleichzeitig aus, mit In-Memory-Kommunikation zwischen beiden.

stackql srv \
  --mcp.server.type=http \
  --mcp.config '{"server": {"transport": "http", "address": "127.0.0.1:9912", "allow_unauthenticated": true}}' \
  --pgsrv.port 5665

Anwendungsfall: wenn Sie sowohl MCP-Protokollzugriff für KI-Agenten als auch das PostgreSQL-Wire-Protokoll für herkömmliche Datenbank-Clients benötigen, mit maximaler Leistung durch In-Memory-Kommunikation.

3. MCP + PostgreSQL-Server (Reverse-Proxy)

Führen Sie beide Server mit TCP-basierter Kommunikation aus, was verteilte Deployments und TLS-Verschlüsselung unterstützt.

stackql srv \
  --mcp.server.type=reverse_proxy \
  --mcp.config '{"server": {"transport": "http", "address": "127.0.0.1:9004", "allow_unauthenticated": true}, "backend": {"dsn": "postgres://stackql:stackql@127.0.0.1:5446?default_query_exec_mode=simple_protocol"}}' \
  --pgsrv.port 5446

Mit TLS-Verschlüsselung:

stackql srv \
  --mcp.server.type=reverse_proxy \
  --mcp.config '{"server": {"tls_cert_file": "/path/to/server_cert.pem", "tls_key_file": "/path/to/server_key.pem", "transport": "http", "address": "127.0.0.1:9004", "auth_token_env_var": "STACKQL_MCP_TOKEN"}, "backend": {"dsn": "postgres://stackql:stackql@127.0.0.1:5446?default_query_exec_mode=simple_protocol"}}' \
  --pgsrv.port 5446

TLS verschlüsselt den Transport, authentifiziert aber nicht den Client; daher erfordert dieses Beispiel zusätzlich das in STACKQL_MCP_TOKEN hinterlegte Bearer-Token.

Anwendungsfall: wenn Sie MCP- und PostgreSQL-Workloads auf verschiedene Prozesse oder Hosts verteilen müssen oder TLS-Verschlüsselung für den MCP-Endpunkt benötigen.

Konfigurationsoptionen

MCP-Servertyp

Typ	Beschreibung
`http`	Direkter HTTP-Servermodus - MCP-Anfragen werden prozessintern von der StackQL-Engine verarbeitet.
`reverse_proxy`	Reverse-Proxy-Modus - MCP-Anfragen werden über den konfigurierten DSN an einen dahinterliegenden PostgreSQL-Server weitergeleitet. Wird mit `stackql srv` verwendet.
`stdio`	Transport über Standardein-/-ausgabe - der Server liest Anfragen von `stdin` und schreibt Antworten nach `stdout`. Wird von in Editoren eingebetteten MCP-Clients (Claude Desktop, Cursor usw.) verwendet.

MCP-Log-Format

Das Flag --mcp.log.format wählt die Kodierung des Audit-Logs: jsonl (Standard) oder otel (OpenTelemetry-OTLP/JSON-Log-Datensätze). Es überschreibt server.audit.format im Konfigurationsobjekt. Siehe Log-Format.

MCP-Protokollversion

Das Flag --mcp.protocol.version legt die neueste Protokollrevision fest, die der Server bekannt gibt: auto (Standard, jede unterstützte Revision), 2026-07-28 (nur sitzungslos) oder eine ältere Revision wie 2025-11-25 (diese Revision und frühere). Es überschreibt server.protocol_version im Konfigurationsobjekt. Siehe Festlegen der Revision.

MCP-Konfigurationsobjekt

Das Flag --mcp.config akzeptiert ein JSON-Objekt mit der folgenden Struktur.

Serverkonfiguration

Feld	Beschreibung	Erforderlich
`server.transport`	Transportprotokoll - `http` oder `stdio`.	Ja
`server.address`	Adresse und Port, an die der MCP-Server gebunden wird (z. B. `127.0.0.1:9912`). Nur für den HTTP-Transport.	Für `http`
`server.tls_cert_file`	Pfad zur TLS-Zertifikatsdatei für HTTPS.	Nein
`server.tls_key_file`	Pfad zur Datei mit dem privaten TLS-Schlüssel für HTTPS.	Nein
`server.auth_token_env_var`	Name einer Umgebungsvariablen, die ein vorab vereinbartes Bearer-Token enthält. Wenn gesetzt, muss jede HTTP-Anfrage `Authorization: Bearer <token>` mitführen; der Server verweigert den Start, wenn die Variable nicht gesetzt oder leer ist. Siehe HTTP-Client-Authentifizierung.	Entweder dieses Feld oder `allow_unauthenticated`, für `http`
`server.allow_unauthenticated`	Ausdrückliches Opt-in, den HTTP-Transport ohne Client-Authentifizierung bereitzustellen. Standard `false`.	Entweder dieses Feld oder `auth_token_env_var`, für `http`
`server.mode`	Sicherheitsvertrag, der Mutationen und Lebenszyklusoperationen absichert. Einer von `read_only`, `safe` (Standard), `delete_safe`, `full_access`. Siehe Servermodi.	Nein
`server.read_only`	Veralteter boolescher Alias für `mode: read_only`. Sind beide Felder gesetzt, gewinnt `mode`.	Nein
`server.stateless`	Stellt Streamable HTTP ohne Sitzungen bereit (keine `Mcp-Session-Id`); so wird Protokollrevision `2026-07-28` über HTTP bereitgestellt. Standard `false`. Wird bei `stdio` ignoriert. Siehe Unterstützung von Protokollrevisionen.	Nein
`server.protocol_version`	Neueste bekannt gegebene Protokollrevision: `auto` (Standard), `2026-07-28` oder eine ältere Revision wie `2025-11-25`. `2026-07-28` impliziert `stateless` für Streamable HTTP. Siehe Festlegen der Revision.	Nein
`server.audit`	Konfiguration des Audit-Subsystems, einschließlich `audit.format` (`jsonl` oder `otel`). Siehe Audit-Log.	Nein

Backend-Konfiguration (nur im Reverse-Proxy-Modus)

Feld	Beschreibung	Erforderlich
`backend.dsn`	PostgreSQL-Verbindungszeichenfolge für den Backend-StackQL-Server.	Ja (für `reverse_proxy`)

info

Der Backend-DSN sollte für optimale Kompatibilität den Parameter default_query_exec_mode=simple_protocol enthalten.

Allowlists

Feld	Beschreibung
`enabled_tools`	Array der Tool-Namen, die der Server veröffentlichen darf. Wenn weggelassen oder leer, wird jedes eingebaute Tool registriert. Dient dazu, eine schmale Teilmenge bereitzustellen (z. B. einen schreibgeschützten Inventar-Server).
`enabled_prompts`	Array von Prompt-Namen. Gleiche Semantik wie `enabled_tools`, aber für die Prompt-Oberfläche.

Beispiel - ein Server, der nur server_info und list_providers veröffentlicht:

{
  "server": {"transport": "http", "address": "127.0.0.1:9912", "allow_unauthenticated": true},
  "enabled_tools": ["server_info", "list_providers"]
}

Unterstützung von Protokollrevisionen

Protokollrevision 2026-07-28, server.stateless und das Audit-Log-Format otel sind in StackQL-Releases ab v0.11.660 verfügbar. server.protocol_version und das Flag --mcp.protocol.version sind in StackQL-Releases ab v0.12.732 verfügbar.

Der Server spricht jede Revision des Model Context Protocol, die das Go MCP SDK unterstützt, und handelt sie pro Client aus, sodass eine Flotte gemischter Clients mit einem Server arbeiten kann.

Revision	Lebenszyklus	Genehmigungsaufforderung (`safe` / `delete_safe`)
`2026-07-28` (bekannt gegeben)	Kein Handshake: `server/discover`, danach führt jede Anfrage `io.modelcontextprotocol/protocolVersion` und `io.modelcontextprotocol/clientCapabilities` in `_meta` mit (plus die Header `Mcp-Protocol-Version`, `Mcp-Method` und `Mcp-Name` bei HTTP).	`input_required`-Ergebnis, vom Client mit `inputResponses` erneut gesendet (SEP-2322).
`2025-11-25`, `2025-06-18`	`initialize`-/`notifications/initialized`-Handshake.	Vom Server initiierte `elicitation/create`-Anfrage.
`2025-03-26`, `2024-11-05`	Wie oben.	Wie oben.

stdio bedient jede Revision in einem Prozess: Die erste Anfrage eines 2026-07-28-Clients wird ohne Handshake bedient, und das initialize eines älteren Clients funktioniert weiterhin. Für Claude Desktop, die npm-/PyPI-Launcher oder das Docker-Image muss nichts konfiguriert werden.

Streamable HTTP verwendet standardmäßig das zustandsbehaftete Modell mit einer Sitzung pro Client (Mcp-Session-Id), das das SDK für Revisionen bis 2025-11-25 bedient. Eine 2026-07-28-Anfrage wird mit dem JSON-RPC-Fehler -32022 beantwortet (nicht unterstützte Protokollversion; ein einfaches HTTP 400 in Releases bis v0.12.718), dessen data.supported die Handshake-Revisionen auflistet, und server/discover gibt dasselbe bekannt, sodass der Client herunterhandelt und bestehende HTTP-Integrationen ihre Sitzungen und ihre Genehmigungsaufforderungen unverändert behalten. Setzen Sie server.stateless (oder legen Sie die Revision auf 2026-07-28 fest, siehe unten), um 2026-07-28 nativ über HTTP bereitzustellen:

stackql mcp \
  --mcp.server.type=http \
  --mcp.config '{"server": {"transport": "http", "address": "127.0.0.1:9912", "allow_unauthenticated": true, "stateless": true}}'

Ein sitzungsloser Server gibt keine Mcp-Session-Id aus, beantwortet GET und DELETE mit 405 (es gibt keine Sitzung, die abgebaut werden könnte), hält tools/list, prompts/list und resources/list verbindungsunabhängig und wickelt die Genehmigungsrunde über input_required ab. Er akzeptiert weiterhin das initialize eines älteren Clients und bedient dessen Lesezugriffe, kann aber die Elicitation-Capability, die dieser Client beim Initialisieren deklariert hat, nicht behalten (jede Anfrage erhält eine flüchtige Sitzung), sodass ältere Clients auf einem sitzungslosen Server keine abgesicherten Schreibvorgänge genehmigen können. Wählen Sie stateless für Hosts mit der aktuellen Revision und die Standardeinstellung für eine Flotte, die noch ältere Clients enthält.

Der Server hält keinen aufrufübergreifenden Zustand: Modus, Audit und Provider-Anmeldedaten sind Konfiguration auf Prozessebene, sodass nichts hinter explizite Handles verschoben werden muss.

Festlegen der Revision

Standardmäßig gibt der Server jede unterstützte Revision bekannt und handelt pro Client aus. Das Flag --mcp.protocol.version oder server.protocol_version im Konfigurationsobjekt (das Flag gewinnt) legt die neueste bekannt gegebene Revision fest:

# sessionless only; stateless Streamable HTTP is implied
stackql mcp \
  --mcp.server.type=http \
  --mcp.protocol.version=2026-07-28 \
  --mcp.config '{"server": {"transport": "http", "address": "127.0.0.1:9912", "allow_unauthenticated": true}}'

# handshake lifecycle only
stackql mcp --mcp.server.type=stdio --mcp.protocol.version=2025-11-25

Wert	Bekannt gegeben	Wirkung
`auto` (Standard) oder nicht gesetzt	Jede unterstützte Revision.	Aushandlung wie oben: die höchste Revision, die beide Seiten sprechen.
`2026-07-28`	Nur `2026-07-28`.	Nur sitzungslos, und `stateless` ist für Streamable HTTP impliziert. Das `initialize` eines älteren Clients wird mit `2025-11-25` beantwortet, das Signal für diesen Client, die Verbindung zu trennen, statt die Antwort als den neuen Lebenszyklus zu lesen.
`2025-11-25` (oder eine beliebige ältere Revision)	Diese Revision und alles davor.	Nur Handshake-Lebenszyklus: Eine `2026-07-28`-Anfrage erhält den JSON-RPC-Fehler `-32022`, dessen `data.supported` die bekannt gegebenen Revisionen auflistet, sodass der Client neu verhandeln kann. Ältere Handshake-Clients behalten ihre eigene Revision.

Jeder andere Wert scheitert beim Start an der Konfigurationsvalidierung, und der Fehler nennt die zulässigen Werte.

Transportgrenzen

Request-Bodys bei Streamable HTTP sind auf 4 MiB begrenzt (darüber HTTP 413), tiefer als 1000 Ebenen verschachteltes JSON wird vor dem Parsen abgewiesen, und ein einzelner stdio-Frame ist auf 8 MiB begrenzt. Keine dieser Grenzen ist konfigurierbar; alle liegen weit über jeder SQL-Anweisung, die der Server akzeptiert.

(Erneutes) Einlesen von Anmeldedaten (`--env.file` + `reload_credentials`)

hinweis

--env.file und das Tool reload_credentials sind in StackQL-Releases nach v0.10.542 verfügbar.

Der Umgebungsblock eines Prozesses wird beim Start festgelegt. Das verursacht zwei Probleme für MCP-Server:

Ein MCP-stdio-Server, den ein Desktop-Client (Claude Desktop, Cursor usw.) ohne die Umgebungsvariablen für die Anmeldedaten startet, kann diese nie sehen - der Client übergibt seine eigene Umgebung an den Unterprozess.
Rotierte kurzlebige Anmeldedaten erreichen eine lang laufende Serversitzung nie.

Das Flag --env.file schließt beide Lücken, indem es eine Datei im dotenv-Stil benennt, die als veränderbarer Speicher für Anmeldedaten dient:

stackql mcp --mcp.server.type=stdio --env.file /path/to/stackql-credentials.env

Semantik des Einlesens

Die Datei wird beim Start für jeden Einstiegspunkt (exec, shell, srv, registry, mcp) in die Prozessumgebung eingelesen:

Ist das Flag leer oder nicht gesetzt, passiert nichts - Anmeldedaten werden zur Anfragezeit verzögert aus der Prozessumgebung aufgelöst, genau wie bisher.
Eine fehlende Datei unter dem angegebenen Pfad wird toleriert und hat keine Wirkung (die Datei kann später erstellt werden).
Eine fehlerhafte oder nicht lesbare Datei führt beim Start zu einem fatalen Fehler.
Nur Schlüssel mit nicht leeren Werten werden gesetzt; vorhandene Prozessumgebungsvariablen werden überschrieben (die Datei ist die maßgebliche Quelle); nichts wird jemals entfernt.
Das Flag gilt nur auf der Kommandozeile - es wird nicht aus .stackqlrc gelesen.

Das Dateiformat ist ein KEY=VALUE pro Zeile. #-Kommentare, Leerzeilen, ein optionales Präfix export , optionale einfache oder doppelte Anführungszeichen um den Wert und CRLF-Zeilenenden werden alle toleriert:

# stackql-credentials.env
export OKTA_SECRET_KEY="00abc...xyz"
STACKQL_GITHUB_USERNAME=myuser
STACKQL_GITHUB_PASSWORD='ghp_mytoken'

`reload_credentials`

Das Tool reload_credentials liest die --env.file-Datei mitten in der Sitzung erneut in die Prozessumgebung ein und meldet anschließend pro Provider den Status der Auflösung der Anmeldedaten. Geheime Werte werden nie zurückgegeben, protokolliert oder auditiert - nur Namen und Status. Ohne konfiguriertes --env.file reduziert sich das Tool auf eine reine Statusprüfung.

Scheitert eine Abfrage an der Auflösung der Anmeldedaten, enthält der MCP-Fehler einen Hinweis, der den Agenten anweist, reload_credentials aufzurufen und es erneut zu versuchen, sodass agentische Clients sich selbst helfen: Schreiben Sie die Anmeldedaten in die Datei, bitten Sie den Agenten um ein Neuladen, und die gescheiterte Abfrage gelingt beim erneuten Versuch - ohne Neustart des Servers.

reload_credentials wird im Backend-Modus reverse_proxy nicht unterstützt - Abfragen werden im entfernten stackql-Serverprozess ausgeführt, daher gibt das Tool einen Fehler zurück, der den Benutzer anweist, auf dem dahinterliegenden Server neu zu laden.

Windows und Claude Desktop

setx schreibt in die Windows-Registrierung, nicht in laufende Prozesse, und Claude Desktop übergibt seine eigene (veraltete) Umgebung an MCP-Unterprozesse - daher erfordern Änderungen an Anmeldedaten normalerweise einen vollständigen Neustart von Claude Desktop. Mit --env.file kann die Datei mit den Anmeldedaten jederzeit erstellt oder rotiert werden, und reload_credentials übernimmt sie ohne Neustart. Eine ausgearbeitete Konfiguration finden Sie unter StackQL mit Claude Desktop verwenden.

HTTP-Client-Authentifizierung

hinweis

server.auth_token_env_var und server.allow_unauthenticated sind in StackQL-Releases ab v0.12.742 verfügbar.

Der HTTP-Transport erfordert eine Client-Authentifizierung. server.auth_token_env_var benennt eine Umgebungsvariable, die ein vorab vereinbartes Bearer-Token enthält; jede Anfrage muss Authorization: Bearer <token> mitführen, sonst wird sie mit 401 beantwortet. Das Token wird aus der Umgebung gelesen, sodass es nie in --mcp.config oder den Prozessargumenten erscheint.

export STACKQL_MCP_TOKEN="$(openssl rand -hex 32)"

stackql mcp \
  --mcp.server.type=http \
  --mcp.config '{"server": {"transport": "http", "address": "127.0.0.1:9912", "auth_token_env_var": "STACKQL_MCP_TOKEN"}}'

Serverauthentifizierung erforderlich

Der Betrieb ohne Token ist ein ausdrückliches Opt-in: Setzen Sie "allow_unauthenticated": true in server. Fehlen beide Schlüssel, beendet sich der Server beim Start mit einer Meldung, die beide nennt; er beendet sich ebenfalls, wenn die Token-Variable nicht gesetzt oder leer ist. Ab dem Release v0.12.742 müssen Sie bei Verwendung des http-Transports entweder auth_token_env_var oder "allow_unauthenticated": true zu server hinzufügen.

TLS (tls_cert_file / tls_key_file) verschlüsselt den Transport, authentifiziert aber nicht den Client; kombinieren Sie es für jeden Listener jenseits von Loopback mit einem Token. Cross-Origin-Anfragen von Browsern (ein nicht übereinstimmender Origin oder ein Cross-Site-Sec-Fetch-Site) werden unabhängig von der Authentifizierung mit 403 abgelehnt. Der mitgelieferte stackql_mcp_client sendet keinen Authorization-Header, daher muss ein Server, den er ansteuert, dem unauthentifizierten Betrieb zugestimmt haben.

Ab v1.0 ersetzt der Start des Servers mit --access.config das gemeinsame Token-Gate durch eine Authentifizierung pro Aufrufer: Jede HTTPS-Anfrage wird mit dem konfigurierten JWT-, statischen Bearer- oder Mutual-TLS-Schema verifiziert und gegen Richtlinienregeln autorisiert. Server-TLS ist in diesem Fall zwingend, die local_os-Authentifizierung wird über HTTP abgelehnt, und eine Anfrage ohne Anmeldedaten fällt nie auf das Umgebungs-Token des Servers zurück. Die Zugriffsverwaltung ist mit dem Servertyp reverse_proxy nicht verfügbar.

Servermodi

server.mode wählt einen von vier Sicherheitsverträgen. Alle vier erlauben SELECT und Metadaten-Lesezugriffe; sie unterscheiden sich darin, wie sie Mutationen und Lebenszyklusoperationen behandeln.

Modus	`SELECT` / Metadaten	`INSERT` / `UPDATE` / `REPLACE`	`DELETE`	`EXEC` (Lebenszyklus)
`read_only`	erlaubt	abgelehnt	abgelehnt	abgelehnt
`safe` (Standard)	erlaubt	Genehmigung erforderlich	Genehmigung erforderlich	Genehmigung erforderlich
`delete_safe`	erlaubt	erlaubt	Genehmigung erforderlich	Genehmigung erforderlich
`full_access`	erlaubt	erlaubt	erlaubt	erlaubt

Abgelehnt gibt sofort einen Fehler an den Client zurück.

Genehmigung erforderlich verwendet den MCP-Elicitation-Ablauf, dessen Form die ausgehandelte Protokollrevision bestimmt:

Hat der Client die Elicitation-Capability bekannt gegeben (beim Initialisieren oder bei 2026-07-28 in den Client-Capabilities in _meta jeder Anfrage), bittet der Server den Benutzer mit einer kurzen Meldung (Tool-Name, Abfrageklasse, SQL), die Aktion zu genehmigen. Bei 2026-07-28 wird die Aufforderung als input_required-Ergebnis zurückgegeben, das eine elicitation/create-Eingabeanfrage unter der ID stackql_approval trägt, und der Client wiederholt den Aufruf mit der Antwort in inputResponses; bei früheren Revisionen sendet der Server die elicitation/create-Anfrage selbst mitten im Aufruf. Der Benutzer akzeptiert, lehnt ab oder bricht ab.
Hat der Client Elicitation nicht bekannt gegeben, wird das Tool mit einer Meldung abgelehnt, die die Lücke erklärt und den Betreiber auf den Modus full_access verweist.

Die Genehmigung wird vom Client beantwortet; sie schützt also davor, dass ein Agent ohne seinen Benutzer handelt, nicht vor einem nicht vertrauenswürdigen Aufrufer. Kombinieren Sie den HTTP-Transport mit Client-Authentifizierung, wo Aufrufer nicht vertrauenswürdig sind.

Der Modus gilt global pro Server. Es gibt keine Überschreibung pro Tool.

Ab v1.0 lehnt run_select_query INSERT, UPDATE, REPLACE, DELETE und EXEC in jedem Modus ab, auch in full_access; der Fehler nennt run_mutation_query oder run_lifecycle_operation. Jedes Tool trägt außerdem einen title und die vier MCP-Verhaltenshinweise als explizite boolesche Werte (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), abgeleitet aus derselben Klassifizierung, die das Policy-Gate durchsetzt. openWorldHint ist true für list_registry, pull_provider, run_select_query, run_mutation_query und run_lifecycle_operation, die Registry- oder Provider-Endpunkte erreichen, und false für Tools, die nur lokalen Zustand lesen. Die Hinweise sind beratend für die Client-UX; die Durchsetzung bleibt beim Policy-Gate.

Payload-Gating

Ab Release v0.12.742 wird eine Payload mit mehreren Anweisungen in jedem Modus nach ihrer privilegiertesten Anweisung abgesichert, sodass SELECT 1; DELETE ... wie ein DELETE behandelt wird und der Audit-Datensatz die query_class mutation_delete trägt. validate_select_query akzeptiert genau eine Anweisung.

Verhaltensänderung des Standardmodus

Frühere Releases setzten Sicherheit nur über ein einzelnes Flag read_only: true/false durch, dessen Standard "keine Durchsetzung" war. Der aktuelle Standard (mode: safe) verlangt für Mutationen von Haus aus die Genehmigung des Benutzers. Betreiber eines Elicitation-fähigen Clients (Claude Desktop, Cursor, Continue usw.) sehen eine Genehmigungsaufforderung pro Mutation. Betreiber von Automatisierung oder des mitgelieferten stackql_mcp_client (der Elicitation nicht bekannt gibt) müssen sich ausdrücklich für mode: full_access entscheiden, um Mutationen und Lebenszyklusoperationen auszuführen.

Der veraltete JSON-/YAML-Schlüssel read_only: true wird aus Gründen der Abwärtskompatibilität weiterhin akzeptiert und als gleichwertig zu mode: read_only behandelt.

Beispiele

# Read-only: SELECTs proceed; mutations and lifecycle refused immediately.
stackql mcp \
  --mcp.server.type=http \
  --mcp.config '{"server": {"transport": "http", "address": "127.0.0.1:9912", "allow_unauthenticated": true, "mode": "read_only"}}'

# Delete-safe: INSERT/UPDATE proceed; DELETE and EXEC need approval.
stackql mcp \
  --mcp.server.type=http \
  --mcp.config '{"server": {"transport": "http", "address": "127.0.0.1:9912", "allow_unauthenticated": true, "mode": "delete_safe"}}'

# Full access: everything proceeds without prompting.  Use only with trusted
# clients and operators.
stackql mcp \
  --mcp.server.type=http \
  --mcp.config '{"server": {"transport": "http", "address": "127.0.0.1:9912", "allow_unauthenticated": true, "mode": "full_access"}}'

Audit-Log

Jeder Tool-Aufruf schreibt einen Datensatz in die konfigurierte Audit-Sink, standardmäßig als JSONL oder als OpenTelemetry-Log-Datensätze (siehe Log-Format). Audit ist standardmäßig eingeschaltet. Das Audit beantwortet "was hat der Agent getan", nicht "was hat der Agent gesehen" - Ergebniszeilen von SELECT-Anweisungen werden in beiden Formaten absichtlich nicht aufgezeichnet.

Was aufgezeichnet wird

Feld	Beschreibung
`timestamp`	Uhrzeit zu Beginn des Aufrufs (RFC3339).
`tool`	Tool-Name (z. B. `run_select_query`).
`mode`	Zum Zeitpunkt des Aufrufs geltender Servermodus.
`decision`	`allow` / `refuse_immediate` / `needs_approval_accepted` / `needs_approval_declined` / `needs_approval_cancelled` / `needs_approval_unavailable`.
`query_class`	`select` / `mutation_create` / `mutation_delete` / `lifecycle` / `unknown`. Bei einer Payload mit mehreren Anweisungen die Klasse der privilegiertesten.
`sql`	SQL-Zeichenfolge für Abfrage-Tools (`run_select_query`, `run_mutation_query`, `run_lifecycle_operation`, `validate_select_query`).
`args`	Hierarchiefelder für Metadaten-Tools (`list_*`, `describe_method`); SQL + `row_limit` für Abfrage-Tools.
`duration_ms`	Dauer von Gate + Handler in Echtzeit.
`error`	Fehlermeldung, wenn das Tool einen Fehler ausgelöst hat oder abgelehnt wurde.

Ergebniszeilen von SELECT-Anweisungen sind bewusst ausgeschlossen - sie können sehr groß sein und sensible Daten enthalten.

Datei-Sink

Die einzige derzeit ausgelieferte Sink ist file. Ein JSON-Objekt pro Zeile, nach jedem Datensatz per fsync gesichert, Rotation im Lumberjack-Stil nach Größe / Alter / Anzahl der Backups.

stackql mcp \
  --mcp.server.type=http \
  --mcp.config '{
    "server": {
      "transport": "http",
      "address": "127.0.0.1:9912",
      "allow_unauthenticated": true,
      "audit": {
        "file": {
          "path": "/var/log/stackql-mcp.log",
          "max_size_mb": 100,
          "max_backups": 5,
          "max_age_days": 30
        }
      }
    }
  }'

Zwei Möglichkeiten, den Speicherort anzugeben:

audit.file.path - ein vollständiger Dateipfad (absolut oder relativ zum aktuellen Arbeitsverzeichnis).
audit.file.dir - ein Verzeichnis; die Sink wählt darin den Basisnamen stackql_mcp_server_<RFC3339-utc-second>.log.

Ist keines von beiden in mcp.config gesetzt, setzt der MCP-Server dir standardmäßig auf das aktuelle Arbeitsverzeichnis, sodass bestehende Betreiber dasselbe Verhalten wie zuvor sehen. Das zugrunde liegende generische Sink-Paket selbst weigert sich, stillschweigend ein Verzeichnis zu wählen - die Entscheidung "wo landen die Logs" trifft immer der Aufrufer.

Der aufgelöste absolute Pfad wird beim Start als sink file: /path/to/file.log nach stderr protokolliert.

Log-Format

Der Audit-Stream hat zwei Kodierungen, die in dieselbe Datei-Sink geschrieben werden:

stackql mcp --mcp.server.type=stdio --mcp.log.format=jsonl   # default, unchanged
stackql mcp --mcp.server.type=stdio --mcp.log.format=otel    # OTLP/JSON log records

Das Flag überschreibt server.audit.format in mcp.config ("audit": {"format": "otel"}). jsonl ist bytekompatibel mit den oben beschriebenen Datensätzen. otel schreibt ein OTLP/JSON-LogsData-Objekt pro Zeile, also die Form, die der otlp_json_file-Receiver des OpenTelemetry Collector unverändert einliest (geprüft gegen otelcol-contrib 0.160.0), sodass der Stream jede OTLP-Pipeline ohne Transform-Prozessor erreicht:

receivers:
  otlp_json_file:
    include: [/var/log/stackql-mcp.log]
exporters:
  debug: {}
service:
  pipelines:
    logs:
      receivers: [otlp_json_file]
      exporters: [debug]

Jeder Tool-Aufruf erzeugt einen Log-Datensatz; ein Aufruf, der das Genehmigungs-Gate durchlaufen hat, erzeugt einen zweiten Datensatz für die Elicitation-Entscheidung. Die Datensätze eines Aufrufs teilen sich gen_ai.tool.call.id und eine Trace-ID. Ein vom Aufrufer in params._meta übergebener W3C-traceparent wird berücksichtigt; andernfalls wird pro MCP-Sitzung eine Trace-ID erzeugt, sodass die Datensätze einer Agentensitzung korrelieren.

Die ausgegebene Attributmenge ist eine versionierte Schnittstelle: Der Instrumentation Scope ist github.com/stackql/stackql/pkg/mcp_server/audit in Version 1.0.0, und schemaUrl fixiert die stabilen Konventionen auf https://opentelemetry.io/schemas/1.44.0. Die Attribute gen_ai.* und mcp.* folgen den semantischen Konventionen für GenAI und MCP, die den Status "Development" haben; die Scope-Version wird erhöht, wenn sich die Menge ändert.

Attribut	Datensatz	Wert
`service.name`, `service.version`	Resource	`stackql`, die StackQL-Version
`gen_ai.operation.name`	Tool-Aufruf	`execute_tool`
`mcp.method.name`	beide	`tools/call` im Tool-Aufruf-Datensatz, `elicitation/create` im Entscheidungsdatensatz
`gen_ai.tool.name`	beide	Tool-Name
`gen_ai.tool.call.id`	beide	Pro Aufruf erzeugt, von beiden Datensätzen geteilt
`mcp.protocol.version`	beide	Ausgehandelte Revision
`mcp.session.id`	beide	Sitzungs-ID (fehlt bei sitzungslosen HTTP-Anfragen)
`stackql.mode`	beide	Servermodus
`stackql.decision`	beide	Der Wert `decision` aus der Tabelle oben
`stackql.query`	Tool-Aufruf	SQL im Wortlaut, für Abfrage-Tools
`stackql.query_class`	Tool-Aufruf	Der Wert `query_class`
`stackql.provider`	Tool-Aufruf	Provider, für Metadaten-Tools
`stackql.query.source`	Tool-Aufruf	ID des Query-Library-Eintrags, falls angegeben
`stackql.duration_ms`	Tool-Aufruf	Dauer in Echtzeit
`stackql.rows_returned`	Tool-Aufruf	Zeilenanzahl, für Tools, die Zeilen zurückgeben
`error.type`, `error.message`	Tool-Aufruf	Bei Fehlschlag: die ablehnende Entscheidung oder `tool_error` nach dem Gate

Der Body ist execute_tool <tool> / elicitation <tool>; der Schweregrad ist INFO oder ERROR, wenn der Aufruf fehlgeschlagen ist oder abgelehnt wurde. Der Schwärzungsvertrag ist in beiden Formaten identisch: Ergebniswerte werden nie serialisiert, nur die Anweisung, die sie erzeugt hat.

Fehlermodi

Gibt die Sink einen Fehler zurück, hängt das Antwortverhalten von audit.failure_mode ab.

failure_mode	Wirkung
`strict` (Standard)	Der Tool-Aufruf gibt den Audit-Fehler an den Client zurück, selbst wenn das zugrunde liegende Tool erfolgreich war. Absichtlich: besser eine mehrdeutige Client-Antwort als ein unentdecktes `DELETE`.
`strict_mutations`	`SELECT` / Metadaten-Lesezugriffe werden mit einem Hinweis auf stderr fortgesetzt; Mutationen und Lebenszyklusoperationen geben den Audit-Fehler zurück.
`best_effort`	Immer nach stderr protokollieren und fortfahren.

Reihenfolge

Der Audit-Schreibvorgang erfolgt nach der Ausführung des Tools (oder seiner Ablehnung durch das Gate), aber bevor die Antwort an den Client zurückgeht. Im strikten Modus bedeutet ein fehlgeschlagener Audit-Schreibvorgang bei einem erfolgreichen DELETE, dass die Zeile weg ist, der Client aber einen Fehler erhält - absichtlich, damit keine Mutation unauditiert durchrutscht.

Audit deaktivieren

Um Audit vollständig abzuschalten (das Verhalten vor PR2):

stackql mcp \
  --mcp.server.type=http \
  --mcp.config '{"server": {"transport": "http", "address": "127.0.0.1:9912", "allow_unauthenticated": true, "audit": {"disabled": true}}}'

Verfügbare MCP-Tools

Beim Betrieb als MCP-Server stellt StackQL die folgenden Tools bereit, vorbehaltlich der konfigurierten enabled_tools-Allowlist. Jedes gibt sowohl eine gerenderte Textansicht (für das LLM) als auch eine typisierte, strukturierte Payload (für programmatische Clients) zurück. Die Standard-Textdarstellung ist eine Markdown-Tabelle für einheitliche mehrzeilige Ergebnisse oder ein Markdown-KV-Block für dünn besetzte Ergebnisse oder Ergebnisse mit einem einzelnen Datensatz. Tools mit Argumenten akzeptieren eine optionale Überschreibung per format (markdown oder json); andernfalls wird die Render-Einstellung des Servers verwendet. Die Eingaben unten listen aufgabenspezifische Argumente auf; ? kennzeichnet optionale Eingaben.

Klicken Sie auf einen Tool-Namen, um die vollständige Referenzseite mit Eingaben, Gating-Verhalten und einem Beispiel-Prompt aufzurufen.

Tool	Renderer	Beschreibung	Eingaben
`server_info`	KV	Serveridentität und Laufzeit: stackql-Version, zugrunde liegende SQL-Engine, Speicherort der Provider-Registry, Modus, Schreibschutz-Flag. Einmal zu Sitzungsbeginn aufrufen.	keine
`list_providers`	Tabelle	Provider, die bereits in den lokalen Cache gezogen wurden - oberste Ebene der Hierarchie.	keine
`list_services`	Tabelle	Services unter einem Provider.	`provider`
`list_resources`	Tabelle	Ressourcen unter einem `provider`.`service`.	`provider`, `service`
`list_methods`	Tabelle	Zugriffsmethoden (HTTP-Operationen) für eine Ressource, mit dem SQL-Verb, auf das jede abgebildet wird, und ihren erforderlichen Parametern. Vor dem Schreiben einer Abfrage aufrufen - hier werden die erforderlichen `WHERE`-Parameter abgeleitet.	`provider`, `service`, `resource`
`describe_method`	KV	Vollständiger I/O-Vertrag für eine Methode (immer EXTENDED): erforderliche und optionale Eingaben sowie die Ausgabefelder, auf die ein `SELECT` verweisen kann.	`provider`, `service`, `resource`, `method`
`query_library_search`	Tabelle	Kuratierte Abfragevorlagen anhand einer Absicht in natürlicher Sprache finden. Nur lesend; Mutationseinträge erfordern ein Opt-in und sind im Modus `read_only` ausgeschlossen.	`intent`, `provider?`, `service?`, `tags?`, `include_mutations?`, `limit?`
`query_library_get`	KV	Eine Vorlage und ihre Parameterdeklarationen abrufen. Mit nicht leeren `params` werden die Werte validiert und das gerenderte SQL plus `next_tool` zurückgegeben, ohne Ausführung.	`id`, `params?`
`validate_select_query`	KV	Ein einzelnes `SELECT` parsen und planen, ohne es auszuführen. Gibt `{valid, errors}` zurück. Nur `SELECT`; genau eine Anweisung.	`sql`
`run_select_query`	Tabelle	Ein `SELECT` ausführen. Gibt `{rows}` zurück. Nur Lesezugriffe.	`sql`, `row_limit?`
`run_mutation_query`	KV	`INSERT`/`UPDATE`/`REPLACE`/`DELETE` gegen den Provider ausführen. Echte Seiteneffekte. Gibt `{messages, timestamp}` zurück. Durch den Modus des Servers abgesichert.	`sql`
`run_lifecycle_operation`	KV	Eine stackql-`EXEC`-Lebenszyklusoperation ausführen. Gibt `{messages, timestamp}` zurück. Durch den Modus des Servers abgesichert.	`sql`
`list_registry`	Tabelle	In der konfigurierten Registry verfügbare Provider (und ihre Versionen). Zu unterscheiden von `list_providers`, das nur bereits gezogene Provider auflistet.	`provider?`
`pull_provider`	KV	Einen einzelnen Provider aus der Registry in den lokalen Cache installieren. Nur Zustand des lokalen Caches - keine Wirkung auf Control Plane oder Data Plane der Cloud.	`provider`, `version?`
`reload_credentials`	Tabelle	Anmeldedaten aus der `--env.file`-dotenv-Datei erneut in die Prozessumgebung einlesen und pro Provider den Auflösungsstatus melden (`ok`, `unresolved`, `not_checked`). Gibt nie geheime Werte zurück. In jedem Modus erlaubt.	`provider?`

Konsultieren Sie query_library_search, bevor Sie SQL von Grund auf schreiben, und verwenden Sie dann query_library_get, um eine passende Vorlage zu prüfen und zu rendern. Abfrage-Tools akzeptieren außerdem ein optionales source mit der ID des Library-Eintrags, ausschließlich zur Zuordnung; die Ausführung unterliegt weiterhin dem normalen Servermodus und der Genehmigungsrichtlinie.

hinweis

describe_resource wurde in StackQL v0.12.732 zurückgezogen; MCP-Clients, Prompts oder Agentenanweisungen, die es aufgerufen haben, sollten stattdessen list_methods gefolgt von describe_method aufrufen. Eine Ressource hat keine einzelne Feldliste, weil jede Zugriffsmethode ihre eigene Form zurückgibt; Spaltennamen stammen daher aus describe_method für die Methode, an die eine Abfrage geleitet wird. Die SQL-Anweisung DESCRIBE ist unverändert.

Verfügbare MCP-Prompts

Ein statischer Prompt wird veröffentlicht.

Prompt	Beschreibung
`write_safe_select`	Anleitung zum Schreiben sicherer `SELECT`-Abfragen gegen stackql-Ressourcen. Erklärt, wie mit `SHOW METHODS IN <provider>.<service>.<resource>` die richtige Lesemethode und die erforderlichen `WHERE`-Parameter ermittelt werden.

Flags

Flag	Beschreibung
`--mcp.server.type`	MCP-Servertyp: `http`, `stdio` oder `reverse_proxy` (Letzterer wird mit `stackql srv` verwendet).
`--mcp.config`	JSON-Konfigurationsobjekt für den MCP-Server. YAML wird ebenfalls akzeptiert.
`--mcp.protocol.version`	Neueste bekannt gegebene Protokollrevision: `auto` (Standard), `2026-07-28` oder eine ältere Revision wie `2025-11-25`. Siehe Festlegen der Revision.
`--env.file`	Datei mit Anmeldedaten im dotenv-Stil, die beim Start eingelesen und vom Tool `reload_credentials` bei Bedarf erneut eingelesen wird. Siehe (Erneutes) Einlesen von Anmeldedaten.
`--pgsrv.port`	TCP-Port für den PostgreSQL-Wire-Protokoll-Server (wird mit `stackql srv` verwendet).
`-H`, `--help`	Hilfeinformationen ausgeben.
`-v`, `--verbose`	Im ausführlichen Modus mit zusätzlicher Ausgabe ausführen.

siehe Globale Flags für weitere Optionen

info

Sie müssen die für die Provider-Authentifizierung erforderlichen Umgebungsvariablen vor dem Start des MCP-Servers setzen oder mit --env.file eine Datei mit Anmeldedaten im dotenv-Stil benennen. Weitere Informationen finden Sie unter Einen Provider verwenden.

Beispiele

Einfacher eigenständiger MCP-Server

Starten Sie einen eigenständigen MCP-Server mit Provider-Authentifizierung und einem Bearer-Token für seine Clients:

export GOOGLE_CREDENTIALS=$(cat /path/to/google-credentials.json)
export STACKQL_MCP_TOKEN="$(openssl rand -hex 32)"

stackql mcp \
  --mcp.server.type=http \
  --mcp.config '{"server": {"transport": "http", "address": "127.0.0.1:9912", "auth_token_env_var": "STACKQL_MCP_TOKEN"}}' \
  --registry='{"url": "https://registry.stackql.io/providers"}' \
  --auth='{"google": {"type": "service_account", "credentialsfilepath": "/path/to/google-credentials.json"}}'

MCP-Server mit PostgreSQL-Server (In-Memory)

Führen Sie MCP- und PostgreSQL-Server für den Zugriff über beide Protokolle aus:

export GOOGLE_CREDENTIALS=$(cat /path/to/google-credentials.json)

stackql srv \
  --mcp.server.type=http \
  --mcp.config '{"server": {"transport": "http", "address": "127.0.0.1:9912", "allow_unauthenticated": true}}' \
  --pgsrv.port 5665 \
  --registry='{"url": "https://registry.stackql.io/providers"}' \
  --auth='{"google": {"type": "service_account", "credentialsfilepath": "/path/to/google-credentials.json"}}'

Schreibgeschützter Inventar-Server mit Audit in einen bekannten Pfad

Nützlich für einen Agenten für Inventar-Scans, der niemals mutieren soll:

stackql mcp \
  --mcp.server.type=http \
  --mcp.config '{
    "server": {
      "transport": "http",
      "address": "127.0.0.1:9912",
      "allow_unauthenticated": true,
      "mode": "read_only",
      "audit": {"file": {"path": "/var/log/stackql-mcp-audit.log"}}
    }
  }' \
  --registry='{"url": "https://registry.stackql.io/providers"}' \
  --auth='{"google": {"type": "service_account", "credentialsfilepath": "/path/to/google-credentials.json"}}'

Automatisierungsserver mit Vollzugriff

Für vertrauenswürdige Automatisierungs-Pipelines, die Mutationen benötigen und nicht auf Elicitation-Aufforderungen antworten können. Die Pipeline legt das in STACKQL_MCP_TOKEN hinterlegte Bearer-Token vor:

stackql mcp \
  --mcp.server.type=http \
  --mcp.config '{
    "server": {
      "transport": "http",
      "address": "127.0.0.1:9912",
      "auth_token_env_var": "STACKQL_MCP_TOKEN",
      "mode": "full_access"
    }
  }' \
  --registry='{"url": "https://registry.stackql.io/providers"}' \
  --auth='{"google": {"type": "service_account", "credentialsfilepath": "/path/to/google-credentials.json"}}'

Abgesicherter MCP-Server mit TLS

Starten Sie einen MCP-Server mit TLS-Verschlüsselung im Reverse-Proxy-Modus:

Erzeugen Sie zunächst TLS-Zertifikate (selbstsigniert für die Entwicklung):

openssl req -x509 -newkey rsa:4096 -keyout server_key.pem -out server_cert.pem -days 365 -nodes

Starten Sie dann den Server:

stackql srv \
  --mcp.server.type=reverse_proxy \
  --mcp.config '{
    "server": {
      "tls_cert_file": "server_cert.pem",
      "tls_key_file": "server_key.pem",
      "transport": "http",
      "address": "127.0.0.1:9004",
      "auth_token_env_var": "STACKQL_MCP_TOKEN"
    },
    "backend": {
      "dsn": "postgres://stackql:stackql@127.0.0.1:5446?default_query_exec_mode=simple_protocol"
    }
  }' \
  --pgsrv.port 5446 \
  --registry='{"url": "https://registry.stackql.io/providers"}' \
  --auth='{"google": {"type": "service_account", "credentialsfilepath": "/path/to/google-credentials.json"}}'

Ihren MCP-Server testen

Das Repository liefert einen Entwicklungs-MCP-Client (stackql_mcp_client) für Skripting und Regressionstests mit. Bauen Sie ihn mit:

python cicd/python/build.py --build-mcp-client

Das erzeugt ./build/stackql_mcp_client.

Beachten Sie, dass stackql_mcp_client keinen Authorization-Header sendet; der Server, den er anspricht, muss daher "allow_unauthenticated": true setzen (wie in den Beispielen oben); ein tokengeschützter Server antwortet ihm mit 401. Er gibt außerdem die MCP-Elicitation-Capability nicht bekannt - er ist für nicht interaktives Skripting gedacht. Gegen einen safe- oder delete_safe-Server erhält er bei Mutations- und Lebenszyklusaufrufen die Ablehnung "client does not support elicitation". Für interaktive Tests mit Elicitation-Aufforderungen verwenden Sie einen in den Editor eingebetteten MCP-Client (Claude Desktop, Cursor, Continue).

# List all available tools
./build/stackql_mcp_client exec \
  --client-type=http \
  --url=http://127.0.0.1:9912

# Server identity, mode, audit / registry context
./build/stackql_mcp_client exec \
  --client-type=http \
  --url=http://127.0.0.1:9912 \
  --exec.action server_info

# Re-source the --env.file credentials file and report per-provider
# credential status - a good first diagnostic when queries fail on auth
./build/stackql_mcp_client exec \
  --client-type=http \
  --url=http://127.0.0.1:9912 \
  --exec.action reload_credentials

# List providers already pulled into the local cache
./build/stackql_mcp_client exec \
  --client-type=http \
  --url=http://127.0.0.1:9912 \
  --exec.action list_providers

# List providers (and versions) available in the registry
./build/stackql_mcp_client exec \
  --client-type=http \
  --url=http://127.0.0.1:9912 \
  --exec.action list_registry

# Install a provider from the registry into the local cache
./build/stackql_mcp_client exec \
  --client-type=http \
  --url=http://127.0.0.1:9912 \
  --exec.action pull_provider \
  --exec.args '{"provider": "kafka"}'

# List services for a provider
./build/stackql_mcp_client exec \
  --client-type=http \
  --url=http://127.0.0.1:9912 \
  --exec.action list_services \
  --exec.args '{"provider": "google"}'

# List access methods for a resource (this is how an agent finds required
# WHERE parameters before writing a query)
./build/stackql_mcp_client exec \
  --client-type=http \
  --url=http://127.0.0.1:9912 \
  --exec.action list_methods \
  --exec.args '{"provider": "google", "service": "compute", "resource": "networks"}'

# Validate a SELECT without executing
./build/stackql_mcp_client exec \
  --client-type=http \
  --url=http://127.0.0.1:9912 \
  --exec.action validate_select_query \
  --exec.args '{"sql": "select name from google.compute.networks where project = '"'"'my-project'"'"';"}'

# Execute a SELECT
./build/stackql_mcp_client exec \
  --client-type=http \
  --url=http://127.0.0.1:9912 \
  --exec.action run_select_query \
  --exec.args '{"sql": "select name from google.compute.networks where project = '"'"'my-project'"'"';"}'

# Mutation - succeeds only against a full_access server, or against
# delete_safe (for INSERT/UPDATE) or safe with an elicitation-capable client.
./build/stackql_mcp_client exec \
  --client-type=http \
  --url=http://127.0.0.1:9912 \
  --exec.action run_mutation_query \
  --exec.args '{"sql": "delete from google.compute.firewalls where project = '"'"'my-project'"'"' and firewall = '"'"'old-rule'"'"';"}'

Beispielantworten

server_info (gegen einen Server im Standardmodus):

{
  "version": "0.10.444",
  "commit": "abc1234",
  "build_date": "2026-05-16T10:47:33Z",
  "platform": "linux/amd64",
  "transport": "http",
  "sql_backend": "sqlite3",
  "provider_registry": "https://registry.stackql.io/providers",
  "mode": "safe",
  "is_read_only": false
}

run_select_query:

{
  "rows": [
    {"name": "default"},
    {"name": "pathfinders-test-01"},
    {"name": "returning-test-03"}
  ]
}

run_mutation_query (gegen einen full_access-Server):

{
  "messages": ["The operation was despatched successfully"],
  "timestamp": "2026-05-16T10:47:33+10:00 AEST"
}

Beispielhafte Audit-Log-Zeile für dieselbe Mutation:

{"timestamp":"2026-05-16T00:47:33Z","tool":"run_mutation_query","mode":"full_access","decision":"allow","query_class":"mutation_delete","sql":"delete from google.compute.firewalls where project = 'my-project' and firewall = 'old-rule';","args":{"sql":"delete from google.compute.firewalls where project = 'my-project' and firewall = 'old-rule';","row_limit":0},"duration_ms":42}

Integration mit KI-Assistenten

Um den MCP-Server von StackQL in einen KI-Assistenten zu integrieren, registrieren Sie stackql als MCP-Server in der Konfiguration des Assistenten. Die meisten in Editoren eingebetteten MCP-Clients betreiben den Server über stdio; verwenden Sie für diese --mcp.server.type=stdio, und der Assistent startet den Prozess direkt. Eigenständige Agenten, die HTTP sprechen, können sich mit einem lang laufenden stackql mcp --mcp.server.type=http-Prozess verbinden.

Für Claude Desktop - einschließlich des Eintrags im Anthropic Connector Directory (die empfohlene Installationsmethode), des herunterladbaren MCP Bundle (.mcpb) und der manuellen Konfiguration - siehe StackQL mit Claude Desktop verwenden.

hinweis

Die Speicherorte der Konfigurationsdateien unterscheiden sich je nach Betriebssystem und KI-Assistent. Den richtigen Pfad und das richtige Format entnehmen Sie der Dokumentation Ihres KI-Assistenten.

Architekturüberlegungen

Berücksichtigen Sie bei der Wahl eines Deployment-Modus:

Eigenständig (stackql mcp): einfachste Einrichtung, ideal für die Entwicklung und für in Editoren eingebettete Clients über stdio.
In-Memory-Doppelserver (stackql srv mit mcp.server.type=http): Ein einzelner Prozess bedient sowohl das MCP- als auch das PostgreSQL-Wire-Protokoll. Beste Leistung, geeignet für die meisten Produktions-Deployments.
Reverse-Proxy (stackql srv mit mcp.server.type=reverse_proxy):
- ermöglicht die Trennung von Workloads über Prozesse oder Hosts hinweg
- unterstützt TLS-Verschlüsselung für abgesicherte MCP-Endpunkte
- erlaubt die unabhängige Skalierung der MCP- und PostgreSQL-Schnittstellen
- bietet Flexibilität für die Integration von Unternehmens-CAs (Hinweis: Die Unterstützung von Unternehmens-CAs ist experimentell)

Und getrennt davon, zur Sicherheit:

Beginnen Sie mit dem Standard mode: safe. Elicitation-fähige Clients (Claude Desktop, Cursor, Continue) fragen den Benutzer vor jeder Mutation.
Legen Sie mode: read_only für Inventar- oder Analyse-Agenten fest, die niemals schreiben sollen.
Legen Sie mode: delete_safe fest, wenn Sie beim Anlegen und Aktualisieren freie Hand lassen, bei destruktiven Operationen aber einen Menschen einbeziehen möchten.
Reservieren Sie mode: full_access für vertrauenswürdige Automatisierungs-Pipelines, und nur in Verbindung mit einem Audit-Log, das jemand prüft.
Setzen Sie server.auth_token_env_var auf jedem HTTP-Listener, den andere Prozesse oder Hosts erreichen können; allow_unauthenticated ist für die lokale Entwicklung gedacht. TLS allein authentifiziert keine Clients.

vorsicht

Bei der Verwendung von TLS mit Zertifizierungsstellen (CAs) von Unternehmen kann zusätzliche Konfiguration erforderlich sein. Diese Funktionalität ist experimentell und erfordert möglicherweise Anpassungen je nach Ihrer konkreten CA-Implementierung.

Weiterführende Informationen

Die Referenz für Paketentwickler ist die pkg/mcp_server-README im stackql-Repository.
Das technische Dokument für Mitwirkende liegt unter docs/mcp.md im stackql-Repository und enthält ausgearbeitete Beispielantworten für jedes Tool.

Syntax​

Deployment-Modi​

1. Eigenständiger MCP-Server​

2. MCP + PostgreSQL-Server (In-Memory)​

3. MCP + PostgreSQL-Server (Reverse-Proxy)​

Konfigurationsoptionen​

MCP-Servertyp​

MCP-Log-Format​

MCP-Protokollversion​

MCP-Konfigurationsobjekt​

Serverkonfiguration​

Backend-Konfiguration (nur im Reverse-Proxy-Modus)​

Allowlists​

Unterstützung von Protokollrevisionen​

Festlegen der Revision​

Transportgrenzen​

(Erneutes) Einlesen von Anmeldedaten (--env.file + reload_credentials)​

Semantik des Einlesens​

reload_credentials​

Windows und Claude Desktop​

HTTP-Client-Authentifizierung​

Servermodi​

Verhaltensänderung des Standardmodus​

Beispiele​

Audit-Log​

Was aufgezeichnet wird​

Datei-Sink​

Log-Format​

Fehlermodi​

Reihenfolge​

Audit deaktivieren​

Verfügbare MCP-Tools​

Verfügbare MCP-Prompts​

Flags​

Beispiele​

Einfacher eigenständiger MCP-Server​

MCP-Server mit PostgreSQL-Server (In-Memory)​

Schreibgeschützter Inventar-Server mit Audit in einen bekannten Pfad​

Automatisierungsserver mit Vollzugriff​

Abgesicherter MCP-Server mit TLS​

Ihren MCP-Server testen​

Beispielantworten​

Integration mit KI-Assistenten​

Architekturüberlegungen​

Weiterführende Informationen​

Syntax

Deployment-Modi

1. Eigenständiger MCP-Server

2. MCP + PostgreSQL-Server (In-Memory)

3. MCP + PostgreSQL-Server (Reverse-Proxy)

Konfigurationsoptionen

MCP-Servertyp

MCP-Log-Format

MCP-Protokollversion

MCP-Konfigurationsobjekt

Serverkonfiguration

Backend-Konfiguration (nur im Reverse-Proxy-Modus)

Allowlists

Unterstützung von Protokollrevisionen

Festlegen der Revision

Transportgrenzen

(Erneutes) Einlesen von Anmeldedaten (`--env.file` + `reload_credentials`)

Semantik des Einlesens

`reload_credentials`

Windows und Claude Desktop

HTTP-Client-Authentifizierung

Servermodi

Verhaltensänderung des Standardmodus

Beispiele

Audit-Log

Was aufgezeichnet wird

Datei-Sink

Log-Format

Fehlermodi

Reihenfolge

Audit deaktivieren

Verfügbare MCP-Tools

Verfügbare MCP-Prompts

Flags

Beispiele

Einfacher eigenständiger MCP-Server

MCP-Server mit PostgreSQL-Server (In-Memory)

Schreibgeschützter Inventar-Server mit Audit in einen bekannten Pfad

Automatisierungsserver mit Vollzugriff

Abgesicherter MCP-Server mit TLS

Ihren MCP-Server testen

Beispielantworten

Integration mit KI-Assistenten

Architekturüberlegungen

Weiterführende Informationen