Cursor-Quickstart

1. Schritt 0

   Konto und Onboarding-Schritt 1

   Registriere dich kostenlos im FrankKi-Partner-Dashboard und schließe Onboarding-Schritt 1 ab. Das dauert ein bis zwei Minuten, du brauchst dafür keinen Menschen auf unserer Seite, keinen unterschriebenen Auftragsverarbeitungsvertrag (AVV) und musst kein Guthaben aufladen. Direkt danach kannst du dir einen Test-Token holen.

2. Schritt 1

   Test-Token holen und Cursor verbinden

   Erzeuge im Dashboard unter /dashboard/tokens im Tab "Test-Token" deinen Token und kopiere ihn sofort, er wird nur einmal im Klartext angezeigt. Trage den FrankKi-Endpunkt in deine Cursor-MCP-Konfiguration ein (projektweit unter .cursor/mcp.json oder global unter ~/.cursor/mcp.json), mit dem Test-Token im Authorization-Header (Konfiguration unten). Cursor bietet für FrankKi aktuell keinen OAuth-Connector an, Token-Paste ist ohnehin der einzige und kanonische Sandbox-Weg.

   {
     "mcpServers": {
       "frankki-sandbox": {
         "url": "https://mcp.frankki.app/api/mcp/v1",
         "headers": {
           "Authorization": "Bearer DEIN_TEST_TOKEN"
         }
       }
     }
   }

3. Schritt 2

   Absenderprofil vervollständigen

   Bevor der erste Versand klappt, prüft FrankKi dein Absenderprofil, das Pflichtangaben-Gate läuft auch in der Sandbox unverändert mit. Rufst du order_send auf einem frischen Konto auf, ohne das Profil vorher ausgefüllt zu haben, bekommst du erwartungsgemäß den Fehler SENDER_PFLICHTANGABEN_INCOMPLETE zurück, mit einem fixUrl direkt zum Absenderprofil-Editor im Dashboard. Öffne den Link, trage Name, Adresse und die weiteren Pflichtfelder ein und rufe order_send danach erneut auf. Das ist ein normaler, eingeplanter Zwischenschritt, kein Fehler in deiner Integration, und passt in die zehn Minuten.

4. Schritt 3

   Grüner Sandbox-Versand

   Bitte deinen Assistenten, die beiden Tools unten mit den gezeigten Argumenten aufzurufen, kein Wert hier ist ein Platzhalter, den du raten musst. order_status wechselt danach von created über accepted nach rund 20 Sekunden zu delivered nach rund 60 Sekunden, simuliert, es geht kein echter Brief raus und es wird nichts berechnet. Rufe order_status mit der zurückgegebenen orderId auf, um den Fortschritt live zu sehen. Die vollständige Parameter-Referenz steht unter /entwickler/tools, jeder Fehlercode (auch SENDER_PFLICHTANGABEN_INCOMPLETE aus Schritt 2) im Fehlerkatalog unter /entwickler/errors.

   // 1) Verbindung und Token prüfen
   mcp_health({})
   
   // 2) Testbrief versenden (0 Cent, kein echter Brief)
   order_send({
     "clientOrderId": "sandbox-quickstart-001",
     "subject": "Testbrief aus der Sandbox",
     "content": "Das ist ein Testbrief aus der FrankKi-Sandbox. Kein Papier, keine Kosten.",
     "recipientName": "Max Mustermann",
     "recipientStreet": "Musterstraße",
     "recipientHouseNumber": "1",
     "recipientZip": "10115",
     "recipientCity": "Berlin"
   })

Konventionen-Panel ansehen →