MCP-Client verbinden

hs-sql-agent stellt unter /mcp einen Streamable HTTP MCP-Endpunkt bereit. Mit der integrierten Administrationsoberfläche besteht der normale Onboarding-Weg nicht darin, Endpunkt und Header manuell zusammenzubauen. Direkt nach der Schlüsselerstellung erzeugt hs-sql-agent eine Clientkonfiguration zum Kopieren.

Empfohlener Onboarding-Ablauf

1. MCP-Schlüssel erstellen

   Öffnen Sie Runtime → MCP Keys, erstellen Sie einen Schlüssel für die Zieldatenbank und erlauben Sie nur die Werkzeuge und Tabellen, die der Client tatsächlich benötigt.

2. Den einmaligen Dialog Save and connect verwenden

   Nach erfolgreichem Issue Key zeigt hs-sql-agent sofort den Klartextschlüssel und die generierten Clientkonfigurationen an. Nur in diesem Moment kann die Administrationsoberfläche den Klartextwert bereitstellen.

3. Client auswählen und Konfiguration kopieren

   Wählen Sie Claude Desktop, Cursor, Visual Studio Code oder Generic HTTP und klicken Sie auf den passenden Button Copy … config. Das kopierte JSON enthält bereits den MCP-Endpunkt und den Header X-MCP-Server-Key.

4. Einfügen, verbinden und bei Bedarf DML prüfen

   Fügen Sie das JSON in die MCP-Clientkonfiguration ein und stellen Sie die Verbindung her. Wenn der Schlüssel DML ausführen darf, testen Sie vor dem Produktionseinsatz sowohl Ablehnung als auch Annahme der Elicitation per Formular.

Öffentlicher Endpunkt für die generierte Konfiguration

Die URL in der Clientkonfiguration stammt aus dieser Servereinstellung:

{
  "Mcp": {
    "PublicEndpoint": "https://sql-agent.example.com/mcp"
  }
}

Die entsprechende Umgebungsvariable ist Mcp__PublicEndpoint; die mitgelieferte Compose-Konfiguration ordnet MCP_PUBLIC_ENDPOINT dieser Einstellung zu.

Konfigurieren Sie vor dem Erstellen von Produktionsschlüsseln die URL, die der MCP-Client tatsächlich erreichen kann, einschließlich /mcp. Die Administrationsoberfläche liest den Wert über GET /api/runtime/client-config und übernimmt ihn direkt in die kopierte Konfiguration.

Vom Dialog erzeugte Konfigurationen

Nach Issue, Rotate oder Duplicate bietet die aktuelle Administrationsoberfläche vier Formate:

• Claude Desktop — direkter HTTP-mcpServers-Eintrag;
• Cursor — HTTP-mcpServers-Eintrag;
• Visual Studio Code — servers-Eintrag;
• Generic HTTP — Streamable-HTTP-Verbindungsobjekt.

Alle Varianten enthalten den konfigurierten Endpunkt und den neu erzeugten MCP-Schlüssel. Im normalen Ablauf muss dieses JSON nicht manuell nachgebaut werden.

Generic / manuelle Authentifizierungsreferenz

Wenn ein Client eine andere äußere Konfigurationsform benötigt, verwenden Sie die Ausgabe unter Generic HTTP als Referenz. Auf Protokollebene erfolgt die Authentifizierung über:

X-MCP-Server-Key: <MCP key>

DML-Kompatibilität separat prüfen

Eine erfolgreiche Verbindung zu /mcp beweist nicht, dass der Client DML-Freigaben unterstützt.

execute_dml_sql und veröffentlichte DML Custom Tools benötigen Elicitation per Formular (form Elicitation). Bevor Sie DML in Produktion zulassen, testen Sie die exakt installierte Clientversion und prüfen Sie beide Pfade:

1. Eine Elicitation-Anfrage ablehnen und sicherstellen, dass die Datenänderung nicht per Commit übernommen wird.
2. Eine Elicitation-Anfrage annehmen und sicherstellen, dass nur die freigegebene Datenänderung abgeschlossen wird.

Nächste Schritte