Model Context Protocol (MCP)

3 Min. Lesezeit

Model Context Protocol (MCP)

PgArachne unterstützt nativ das Model Context Protocol (MCP), einen offenen Standard, der es KI-Modellen (wie Claude oder Cursor) ermöglicht, sicher auf Ihre Daten und Funktionen als „Tools" zuzugreifen.

Wie funktioniert es?

PgArachne agiert direkt als MCP-Server. Anstatt für jedes Projekt einen eigenen HTTP-Server zu schreiben, starten Sie PgArachne einfach über Ihrer Datenbank. PgArachne analysiert automatisch Ihre erlaubten SQL-Funktionen und stellt sie KI-Clients über HTTP(S) zur Verfügung.

🛠️ SQL-Funktionen als Tools

Jede SQL-Funktion, die über den JSON-RPC-2.0-Endpunkt von PgArachne erreichbar ist, wird automatisch zu einem „Tool", das der KI zur Verfügung steht. Das Standardverhalten (Aufruf von pgarachne.allowed_schemas()) gibt Funktionen aus dem api-Schema frei, auf die der authentifizierte Benutzer Zugriff hat (via GRANT EXECUTE). Das LLM sieht den Funktionsnamen, die Parameter und die Beschreibung aus den SQL-Kommentaren.

Verbindungsanleitung

1 a. Authentifizierung — API-Token (empfohlen für Produktion)

Für eine dauerhafte KI-Verbindung verwenden Sie ein langlebiges API-Token. Das Token muss von einem Administrator (einem Mitglied der Rolle pgarachne_admin) generiert werden:

-- Zur Administrator-Rolle wechseln
SET ROLE pgarachne_admin;

-- Neues Token für die Zielrolle generieren (z. B. 'app_user')
SELECT pgarachne.add_api_token('Claude Desktop', 'app_user');

Speichern Sie den zurückgegebenen Wert. Verwenden Sie ihn als Authorization: Bearer IHR_API_TOKEN in der Konfiguration des KI-Clients.

1 b. Authentifizierung — Direkte Zugangsdaten (Entwicklung & einfache Setups)

Alternativ können Sie PostgreSQL-Benutzername und Passwort direkt über HTTP Basic Authentication übermitteln. Es ist kein Token-Management erforderlich und kein GRANT … TO pgarachne notwendig — PgArachne verbindet sich direkt als der angegebene Benutzer.

Authorization: Basic <base64(benutzername:passwort)>

Verwenden Sie diesen Ansatz für lokale Tests oder interne Dienste, bei denen Zugangsdaten bereits sicher verwaltet werden. Für produktive KI-Integrationen mit Cloud-Clients sind API-Token die bevorzugte Wahl.

2. Claude Desktop

Fügen Sie PgArachne zu Ihrer Claude Desktop-Konfiguration hinzu (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "pgarachne": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-http",
        "--url",
        "https://ihre-api.com/db/my_database/mcp"
      ],
      "env": {
        "Authorization": "Bearer IHR_API_TOKEN"
      }
    }
  }
}

Hinweis: HTTP(S) ist erforderlich für die Verbindung. Das Beispiel verwendet die server-http-npx-Bridge von Anthropic, die als Vermittler zwischen Standard-MCP (stdio) und PgArachne (HTTP) fungiert.

3. Cursor

Fügen Sie in den Cursor-Einstellungen (Einstellungen > MCP) einen neuen Server hinzu, der direkt über HTTP kommuniziert (oder verwenden Sie die oben genannte Bridge, falls Ihre Cursor-Version keine nativen HTTP-MCP-Server unterstützt):

Typ: command (mit npx-Bridge) oder http
Name: PgArachne
URL: https://ihre-api.com/db/my_database/mcp
Auth-Header: Authorization: Bearer IHR_API_TOKEN

🌐 Öffentliche Erreichbarkeit (Ngrok)

Wenn Sie PgArachne lokal testen und mit einem cloudbasierten KI-Client verbinden möchten (außerhalb lokaler Installationen), muss Ihr Server über eine HTTP(S)-URL öffentlich erreichbar sein.

# Ngrok für den HTTP-PgArachne-Port starten (z. B. 8080)
ngrok http 8080

Verwenden Sie anschließend die von Ngrok generierte HTTPS-Adresse in der KI-Konfiguration.

Sicherheit

Der MCP-Endpunkt respektiert vollständig das PostgreSQL-Berechtigungssystem:

Authentifizierung: Jede Anfrage erfordert ein gültiges API-Token, JWT oder HTTP-Basic-Zugangsdaten; nicht authentifizierte Anfragen werden sofort abgelehnt.
Autorisierung: Die KI kann nur jene Funktionen in erlaubten Schemata sehen und aufrufen, für die die authentifizierte Rolle GRANT EXECUTE besitzt.
RLS: Row-Level Security ist vollständig aktiv — die KI sieht nur die Zeilen, auf die die jeweilige Rolle Zugriff hat.

Eine vollständige Übersicht aller unterstützten Authentifizierungsmethoden finden Sie unter Sicherheit & Authentifizierung.

← JSON-RPC (Hello World) Werkzeuge →

Model Context Protocol (MCP)