MCP für GBL

Ein sicherer, mandantenfähiger Model Context Protocol (MCP)-Server für den Zugriff auf markenspezifische Postgres-Datenbanken. Dieser Server unterstützt sowohl die lokale Ausführung als auch den authentifizierten Remote-Zugriff über HTTP/SSE.

🔐 Authentifizierung & Sicherheit

Dieser Server verwendet Bearer-Token-Authentifizierung. Der Zugriff auf die Endpunkte /sse und /messages erfordert einen gültigen API-Schlüssel mit dem Präfix gbl-.

Key Management CLI

Verwalten Sie Ihre Schlüssel lokal oder auf EC2 mithilfe des integrierten Auth-Moduls:

# Activate your environment first
source .venv/bin/activate  # Linux/EC2
.\.venv\Scripts\activate   # Windows

### 6. Manage Multi-Tenant API Keys (Admin API)
To provision unique database tenants to separate keys, we host an internal Admin REST API.
This API handles secrets, so it should **only** be accessed from localhost on your EC2 instance (binds to `:8001`).

### Option A: Use it securely locally via SSH Tunneling (Recommended)
You can build a secure tunnel from your Windows PC directly to your EC2 instance so you can interact with the Admin API from your own local browser (like Swagger UI) or local terminal smoothly:
```powershell
# Run this on your local Windows PC
ssh -i "path/to/your/key.pem" -L 8001:127.0.0.1:8001 ubuntu@YOUR_EC2_IP

Jetzt können Sie direkt von Ihrem lokalen Rechner aus mit der API interagieren oder die Swagger-UI aufrufen: http://127.0.0.1:8001/docs

Option B: Direkte Verwendung auf EC2

So starten Sie die Admin-API auf EC2:

python3 -m src.admin_api

Sobald die Admin-API läuft, können Sie in einem anderen EC2-Terminalfenster einen neuen Mandantenschlüssel für eine Marke erstellen:

curl -X POST http://127.0.0.1:8001/keys/generate \
     -H "Content-Type: application/json" \
     -d '{"db_user": "brand_a_user", "db_pass": "supersecret"}'

(Die Antwort enthält den api_key, der brand_a_user zugewiesen wurde.)

Weitere Hilfs-Endpunkte:

• Mandanten auflisten: curl http://127.0.0.1:8001/keys

• Mandanten widerrufen: curl -X DELETE http://127.0.0.1:8001/keys/brand_a_user

🖥️ EC2-Bereitstellung (Persistenz mit systemd)

Für die Produktion verwenden wir systemd, um sicherzustellen, dass der Server beim Neustart automatisch startet und bei einem Absturz neu gestartet wird.

1. Projekteinrichtung

git clone https://github.com/intern-analytics/MCPforGBL.git
cd MCPforGBL
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. Konfiguration

Erstellen Sie eine .env-Datei für Datenbankanmeldedaten (gitignored):

nano .env
# Add DB_USER, DB_PASS, DB_HOST, etc.

3. Erstellen des Systemdienstes

Erstellen Sie eine Dienstdatei:

sudo nano /etc/systemd/system/mcp-server.service

Fügen Sie Folgendes ein (passen Sie die Pfade bei Bedarf an):

[Unit]
Description=Brand MCP FastAPI Server
After=network.target

[Service]
User=ubuntu
WorkingDirectory=/home/ubuntu/projects/MCPforGBL
ExecStart=/home/ubuntu/projects/MCPforGBL/.venv/bin/python -m src.server2
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

4. Aktivieren und Starten

sudo systemctl daemon-reload
sudo systemctl enable mcp-server
sudo systemctl start mcp-server
sudo systemctl status mcp-server

🤖 Verbindung zu Claude

Option A: Verwendung von Claude.ai (Web-App)

Da dieser Server öffentlich über Nginx zugänglich ist und durch ein Let's Encrypt HTTPS-Zertifikat geschützt wird, können Sie sich direkt in Ihrem Browser verbinden.

1. Gehen Sie zu Claude.ai Einstellungen -> Developer / Connectors.

2. Klicken Sie auf Add custom connector.

3. Fügen Sie Ihre sichere URL ein: https://mcpforgbl.duckdns.org/sse?token=gbl-YOUR_KEY_HERE

4. Verbinden und abfragen!

Option B: Verwendung der Claude Desktop App (HTTPS)

Aktualisieren Sie Ihre %APPDATA%\Claude\claude_desktop_config.json unter Windows.

{
  "mcpServers": {
    "gbl-data-lake": {
      "command": "C:\\PROGRA~1\\nodejs\\npx.cmd",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcpforgbl.duckdns.org/sse?token=gbl-YOUR_KEY_HERE"
      ]
    }
  }
}

Option C: Verwendung der Claude Desktop App (HTTP IP-Adresse & Bearer-Header)

Wenn Sie sich lieber direkt mit der IP-Adresse der EC2-Instanz verbinden möchten, ohne die DuckDNS-URL zu verwenden, oder das Token als Header statt als URL-Parameter übergeben möchten, verwenden Sie diese Konfiguration:

{
  "mcpServers": {
    "gbl-data-lake": {
      "command": "C:\\PROGRA~1\\nodejs\\npx.cmd",
      "args": [
        "-y",
        "mcp-remote",
        "http://YOUR-EC2-PUBLIC-IP:8000/sse",
        "--allow-http",
        "--header",
        "Authorization: Bearer gbl-YOUR_KEY_HERE"
      ]
    }
  }
}

📈 Skalierbarkeits-Roadmap

Unsere Plattform ist darauf ausgelegt, durch ein robustes, rollenbasiertes Zugriffskontrollsystem sicher und effizient zu skalieren.

Wir planen, die Benutzerverwaltung durch die Generierung separater, dedizierter API-Schlüssel für jeden Benutzer/Mandanten zu skalieren. In unserer Architektur fungiert der API-Schlüssel nicht nur als Authentifizierungs-Token, sondern definiert inhärent das vollständige Berechtigungsprofil eines Benutzers. Der Schlüssel selbst teilt dem Server genau mit, wie viel Zugriff der Benutzer hat.

Dieser Ansatz ermöglicht es uns, Datenbankinteraktionen und die Verfügbarkeit von Tools basierend auf Konten mit eingeschränktem Zugriff und angepassten Skill-Dateien strikt durchzusetzen, wodurch sichergestellt wird, dass jeder Benutzer nur mit den Daten und Funktionen interagiert, für die er explizit autorisiert ist.

🛠️ Entwicklung

• Lokaler Server: python -m src.server (Standard stdio)

• SSE-Server: python -m src.server2 (HTTP/SSE über FastAPI)

• Auth-Utils: src/auth.py

• Datenbanklogik: src/db.py