API & MCP — Slonge Billing automatisieren

Slonge Billing bietet eine offizielle Kommandozeilen-Schnittstelle (CLI) und einen MCP-Server (Model Context Protocol) für Claude Desktop, Cursor und Claude Code. Damit können Sie Ihren Tenant programmatisch oder über KI-Agenten ansprechen — Kunden anlegen, Rechnungen erstellen, Berichte abrufen, alles ohne Klicken im Web-UI.

Für wen ist das?

• CLI-Nutzer: Entwickler:innen, Buchhalter:innen oder Power-User, die Routineaufgaben automatisieren oder in eigene Skripte einbinden möchten.
• KI-Agent-Nutzer: Wer Claude Desktop, Cursor oder Claude Code (oder einen anderen MCP-fähigen Agenten) nutzt und die Slonge-Funktionen direkt aus dem Chat heraus verwenden will — „Lege mir den Kunden Beispiel AG mit der E-Mail … an" oder „Welche Rechnungen sind diese Woche überfällig?".
• Voraussetzung: Rolle Administrator im Tenant — nur Administratoren können API-Tokens erstellen oder widerrufen.

Schnellstart in 5 Minuten

Schritt 1: API-Token erstellen

1. Anmelden bei Slonge Billing.
2. Einstellungen öffnen.
3. Auf den Tab API & MCP wechseln.
4. Token erstellen klicken.
5. Sprechenden Namen vergeben (z. B. „Claude Desktop", „CI-Pipeline").
6. Optional: Ablauf wählen (30 / 90 / 365 Tage oder „Nie").
7. Erstellen klicken — der vollständige Token wird genau einmal angezeigt. Kopieren Sie ihn sofort. Nach dem Schliessen des Dialogs lässt er sich nicht mehr abrufen.

Sicherheit: Tokens werden als SHA-256-Hash gespeichert. Slonge selbst kann den Klartext nach der Erstellung nicht mehr einsehen. Geht ein Token verloren, widerrufen Sie ihn und erstellen einen neuen.

Schritt 2A: CLI verwenden

# Einmalig: Konfiguration setzen
slonge config set api-url https://app.slonge-billing.ch
slonge config set api-token slk_live_IHR_TOKEN_HIER
slonge config test       # bestätigt Bearer-Authentifizierung

# Tägliche Befehle
slonge client list
slonge client create --name "Beispiel AG" --email [email protected]
slonge invoice list --status pending --limit 10
slonge invoice create --project-id <id> --amount 1500 --description "Beratungsleistung Mai"
slonge invoice mark-paid <rechnungs-id>

Globale Flags (für alle Befehle verfügbar):

• --json — gibt eine JSON-Antwort statt einer Tabelle aus (ideal für Skripte)
• --verbose — protokolliert HTTP-Aufrufe nach stderr
• --dry-run — validiert die Eingabe und zeigt den geplanten Aufruf, ohne ihn auszuführen

Die CLI speichert die Konfiguration in ~/.slonge/config.json (Windows: %USERPROFILE%\.slonge\config.json).

Schritt 2B: MCP-Server in Claude Desktop einbinden

1. Konfiguration in %APPDATA%\Claude\claude_desktop_config.json (Windows) bzw. ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ergänzen:

   {
     "mcpServers": {
       "slonge-billing": {
         "command": "node",
         "args": ["<absoluter-pfad>/packages/mcp-server/dist/index.js"],
         "env": {
           "SLONGE_CONFIG_PATH": "<absoluter-pfad>/.slonge/config.json"
         }
       }
     }
   }
   

2. Claude Desktop vollständig beenden (nicht nur Fenster schliessen — auch das Tray-Symbol) und neu starten.

3. Im Chat erscheint ein 🔌-Symbol mit dem Eintrag slonge-billing und rund 20 verfügbaren Tools.

4. Im Gespräch fragen: „Liste mir die offenen Rechnungen aus Slonge" — Claude ruft das passende Tool auf und zeigt das Ergebnis direkt im Chat.

Die gleichen Schritte funktionieren mit Cursor und Claude Code (über deren jeweilige MCP-Konfiguration).

Verfügbare Funktionen

Sowohl CLI als auch MCP-Server greifen auf dieselbe API zu — die Funktionalität ist identisch.

Neue Tools (Wave 6)

E-Rechnung (Peppol BIS Billing 3.0)

CLI-Kurzbefehl:

slonge invoice ubl <id> -o rechnung.xml   # schreibt die XML auf Disk
slonge invoice ubl <id>                   # streamt die XML auf stdout

Eine vollständige Liste der MCP-Tool-Namen (im Format client_list, invoice_create etc.) erhalten Sie über tools/list Ihres MCP-Clients.

Authentifizierung & Limits

• Bearer-Token — jeder Aufruf braucht den Header Authorization: Bearer slk_<env>_<token>.
• Tenant-Bindung — der Token kennt seinen Tenant; ein Tenant-Wechsel ist im Token nicht möglich. Wer mehrere Tenants verwaltet, erstellt pro Tenant einen eigenen Token.
• Rate-Limit — 60 Anfragen pro Minute pro Token. Bei Überschreitung antwortet die API mit 429 Too Many Requests und dem Header Retry-After.
• Audit-Log — jeder Zugriff wird protokolliert (Zeitpunkt, Methode, Pfad, Statuscode, Antwortzeit).

AI-Quota

Werkzeuge, die OpenAI verwenden — derzeit nur expense upload / expense_upload — gelten gegen das monatliche AI-Limit Ihres Plans (aiCallsPerMonth).

Bei Erreichen des Limits antwortet die API mit 429 QUOTA_EXCEEDED. Aufrufe gegen einen Plan ohne AI-Features antworten mit 403 FORBIDDEN. Beide Codes haben deterministische Bedeutung — Agenten können unterscheiden zwischen „warten und nochmal versuchen" (Rate-Limit) und „Plan upgraden" (Quota).

Fehlercodes

Die API antwortet immer mit der gleichen Hüllenstruktur:

{ "success": false, "error": { "code": "VALIDATION_ERROR", "message": "...", "details": { } } }

Sicherheit & Best Practices

• Token niemals committen — .gitignore für .env-Dateien und ~/.slonge/config.json ist Pflicht.
• Einen Token pro Anwendung — jede CI-Pipeline, jeder Laptop, jeder Agent bekommt einen eigenen Token. So lässt sich gezielt widerrufen, wenn ein Gerät verloren geht.
• Sprechende Namen vergeben — der Token-Name erscheint im Audit-Log und in der Übersicht; „Claude Desktop — Laptop Ben" sagt mehr als „Token 1".
• Bei Verdacht widerrufen — Widerruf ist sofort wirksam; der Token kann nicht reaktiviert werden.
• Ablaufdatum nutzen — für temporäre Integrationen (z. B. ein einmaliger Migrationslauf) lieber 30 Tage statt „Nie".

Streamable HTTP Transport

Neben dem lokalen slonge-mcp (stdio) bietet Slonge Billing einen gehosteten MCP-Endpunkt:

POST https://app.slonge-billing.ch/api/mcp
Authorization: Bearer slk_...
Accept: application/json, text/event-stream

Verbinden Sie kompatible Clients (claude.ai, ChatGPT, Cursor mit Remote-MCP-Unterstützung) direkt mit dieser URL — keine Installation nötig. Die gleichen API-Tokens funktionieren über stdio und HTTP.

Nächste Schritte

• Token erstellen: Einstellungen → API & MCP
• Kontaktieren Sie uns unter [email protected], wenn Sie Fragen zur Einrichtung haben oder neue MCP-Tools wünschen.

Hinweis für Entwickler:innen: Die offizielle SDK heisst @slonge/agent-sdk und enthält Zod-Schemata und einen typisierten HTTP-Client. Sie wird gemeinsam mit der CLI und dem MCP-Server im Slonge-Billing-Monorepo gepflegt.