MCP Service - Production Ready Setup

Ein vollständiges, produktionsfertiges MCP-Connector-Service mit DuckDB-Backend, WorkOS OAuth und automatischem SSL.

Features

• FastAPI + FastMCP - Modernes Python-Framework
• DuckDB Integration - Lokale oder MotherDuck Cloud-Datenbank
• WorkOS OAuth - Enterprise-ready Authentication
• Nginx Reverse Proxy - Production-grade Routing
• Let's Encrypt SSL - Automatische HTTPS-Zertifikate
• Docker Compose - Einfaches Deployment
• Health Checks - Monitoring-ready

Voraussetzungen

• Docker & Docker Compose installiert
• Domain mit DNS A-Record auf deinen Server
• Ports 80 und 443 offen
• WorkOS Account (für Auth)

Schnellstart

1. Projekt klonen/herunterladen

# Projektverzeichnis erstellen
mkdir mcp-service && cd mcp-service
# Alle Dateien hierhin kopieren

2. Umgebungsvariablen konfigurieren

cp .env.example .env
nano .env

Fülle folgende Werte aus:

# Deine Domain
DOMAIN=mcp.yourdomain.com

# WorkOS Credentials (von https://dashboard.workos.com/)
WORKOS_CLIENT_ID=client_xxx
WORKOS_CLIENT_SECRET=sk_xxx

# Secret Key generieren:
# openssl rand -hex 32
SECRET_KEY=generierter_secret_key

# Datenbank (lokal oder MotherDuck)
MD_CONNECTION=mydata.db
# Oder für MotherDuck:
# MD_CONNECTION=md:your_motherduck_token

# Auth aktivieren
REQUIRE_AUTH=true

3. WorkOS konfigurieren

1. Gehe zu WorkOS Dashboard
2. Erstelle eine neue Application
3. Füge Redirect URI hinzu: https://mcp.yourdomain.com/oauth/callback
4. Kopiere Client ID und Secret in .env

4. SSL-Zertifikat einrichten

./setup-ssl.sh

Das Script:

• Erstellt notwendige Verzeichnisse
• Konfiguriert Nginx
• Holt Let's Encrypt Zertifikat
• Validiert DNS-Konfiguration

5. Services starten

docker-compose up -d

6. Logs prüfen

# Alle Services
docker-compose logs -f

# Nur MCP App
docker-compose logs -f mcp

# Nur Nginx
docker-compose logs -f nginx

7. Testen

# Health Check
curl https://mcp.yourdomain.com/health

# Manifest abrufen
curl https://mcp.yourdomain.com/mcp/manifest

Verwendung in Claude/ChatGPT

In Claude Desktop

1. Öffne Claude Desktop Settings
2. Gehe zu "Model Context Protocol"
3. Füge hinzu:
   • Name: MyDataMCP
   • URL: https://mcp.yourdomain.com/mcp
4. Wenn Auth aktiviert: Klicke "Authenticate"

In ChatGPT

1. Öffne ChatGPT Settings
2. Gehe zu "Actions" oder "Custom GPTs"
3. Füge Server hinzu: https://mcp.yourdomain.com/mcp

Verfügbare Tools

1. create_table

Importiert CSV oder Google Sheets in DuckDB.

{
  "source_url": "https://example.com/data.csv",
  "table_name": "sales_data"
}

Google Sheets Support:

• URL Format: https://docs.google.com/spreadsheets/d/SHEET_ID/edit
• Wird automatisch zu CSV-Export konvertiert

2. query

Führt SQL-Abfragen aus.

{
  "sql": "SELECT * FROM sales_data WHERE amount > 1000 LIMIT 10"
}

3. list_tables

Listet alle Tabellen auf.

{}

4. describe_table

Zeigt Schema und Beispieldaten.

{
  "table_name": "sales_data"
}

Beispiel-Workflow

# 1. CSV importieren
curl -X POST https://mcp.yourdomain.com/mcp/tools/create_table \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_url": "https://people.sc.fsu.edu/~jburkardt/data/csv/airtravel.csv",
    "table_name": "airtravel"
  }'

# 2. Tabellen anzeigen
curl https://mcp.yourdomain.com/mcp/tools/list_tables \
  -H "Authorization: Bearer YOUR_TOKEN"

# 3. Daten abfragen
curl -X POST https://mcp.yourdomain.com/mcp/tools/query \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT * FROM airtravel LIMIT 5"
  }'

Authentifizierung

OAuth Flow (Browser)

1. Öffne https://mcp.yourdomain.com/oauth/login
2. Login mit WorkOS Provider
3. Redirect zurück mit Session Cookie

API Token (Programmatisch)

# Token von WorkOS holen
# Dann in Header verwenden:
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://mcp.yourdomain.com/mcp/tools/list_tables

Auth deaktivieren (nur Development!)

REQUIRE_AUTH=false

Wartung

Services neu starten

docker-compose restart

Logs rotieren

docker-compose logs --tail=100 -f

SSL-Zertifikat erneuern

Certbot erneuert automatisch alle 12 Stunden. Manuell:

docker-compose run --rm certbot renew
docker-compose restart nginx

Backup erstellen

# Datenbank sichern
docker-compose exec mcp tar czf /data/backup.tar.gz /data/mydata.db

# Backup herunterladen
docker cp mcp:/data/backup.tar.gz ./backup.tar.gz

Updates einspielen

# Images neu bauen
docker-compose build --no-cache

# Services neu starten
docker-compose up -d

MotherDuck Integration

Für Cloud-DuckDB:

1. Hole Token von MotherDuck
2. Update .env:

MD_CONNECTION=md:your_motherduck_token

1. Restart:

docker-compose restart mcp

Troubleshooting

Problem: Ports bereits belegt

# Prüfe welcher Service Port 80/443 nutzt
sudo netstat -tlnp | grep ':80\|:443'

# Stoppe konkurrierende Services
sudo systemctl stop apache2
sudo systemctl stop nginx

Problem: DNS nicht aufgelöst

# Prüfe DNS
nslookup mcp.yourdomain.com

# Prüfe A-Record
dig mcp.yourdomain.com +short

Problem: SSL-Zertifikat fehlgeschlagen

# Debug-Modus
docker-compose run --rm certbot certonly \
  --webroot \
  --webroot-path=/var/www/certbot \
  --email admin@yourdomain.com \
  --agree-tos \
  --dry-run \
  -d mcp.yourdomain.com

Problem: OAuth Redirect fehlt

# Prüfe WorkOS Dashboard:
# 1. Redirect URI muss exakt sein
# 2. HTTPS erforderlich
# 3. Keine trailing slashes

# Korrekt:
https://mcp.yourdomain.com/oauth/callback

# Falsch:
http://mcp.yourdomain.com/oauth/callback/

Problem: 502 Bad Gateway

# Prüfe ob MCP-App läuft
docker-compose ps

# Prüfe App-Logs
docker-compose logs mcp

# Health Check
curl http://localhost:8000/health

Problem: Datenbank Permissions

# Fix Permissions
sudo chown -R 1000:1000 ./data
sudo chmod -R 755 ./data

Sicherheit

Production Checklist

• REQUIRE_AUTH=true gesetzt
• SECRET_KEY mit starkem Wert
• Firewall konfiguriert (nur 80, 443 offen)
• SSL-Zertifikat aktiv
• WorkOS korrekt konfiguriert
• ALLOWED_ORIGINS eingeschränkt
• Backups eingerichtet
• Monitoring aktiv

Empfohlene Firewall-Regeln

# UFW (Ubuntu)
sudo ufw allow 22/tcp    # SSH
sudo ufw allow 80/tcp    # HTTP
sudo ufw allow 443/tcp   # HTTPS
sudo ufw enable

Rate Limiting (optional)

Füge in nginx/conf.d/mcp.conf hinzu:

limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;

location /mcp/ {
    limit_req zone=api burst=20 nodelay;
    # ... rest of config
}

Monitoring

Prometheus Metrics (optional)

Füge in requirements.txt hinzu:

prometheus-fastapi-instrumentator==6.1.0

In app.py:

from prometheus_fastapi_instrumentator import Instrumentator

Instrumentator().instrument(app).expose(app)

Uptime Monitoring

Nutze Services wie:

• UptimeRobot
• Pingdom
• StatusCake

Endpoint: https://mcp.yourdomain.com/health

Performance-Tipps

DuckDB Optimierung

# In app.py bei get_db_conn():
con.execute("SET memory_limit='4GB'")
con.execute("SET threads=4")

Nginx Caching

# In nginx/conf.d/mcp.conf
proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=api_cache:10m max_size=100m;
proxy_cache api_cache;
proxy_cache_valid 200 5m;

Lizenz & Support

• Lizenz: MIT
• Issues: [GitHub Repository]
• Docs: [Documentation URL]

Changelog

v1.0.0 (2024-11)

• Initial Release
• WorkOS OAuth Integration
• Nginx + Let's Encrypt Setup
• DuckDB + MotherDuck Support
• 4 MCP Tools (create_table, query, list_tables, describe_table)