Cursor Quickstart

1. Step 0

   Account and onboarding step 1

   Sign up for free in the FrankKi partner dashboard and complete onboarding step 1. This takes one to two minutes, needs no human on our side, no signed data-processing agreement (AVV) and no wallet top-up. Right after that you can mint a test token.

2. Step 1

   Get a test token and connect Cursor

   Mint your token under the "Test token" tab at /dashboard/tokens in the dashboard and copy it right away, it is shown in plain text only once. Add the FrankKi endpoint to your Cursor MCP config (project-wide in .cursor/mcp.json, or globally in ~/.cursor/mcp.json), with the test token as the Authorization header (config below). Cursor does not currently offer an OAuth connector for FrankKi, token-paste is the only and canonical sandbox path either way.

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

3. Step 2

   Complete your sender profile

   Before the first send goes through, FrankKi checks your sender profile, the Pflichtangaben hard gate runs unchanged in the sandbox too. If you call order_send on a fresh account before filling it in, you will get back SENDER_PFLICHTANGABEN_INCOMPLETE with a fixUrl straight to the sender profile editor in the dashboard. Open that link, fill in name, address and the remaining required fields, then call order_send again. This is an expected, planned step, not a bug in your integration, and it is budgeted into the 10 minutes.

4. Step 3

   Green sandbox send

   Ask your assistant to call the two tools below with the shown arguments; no value here is a placeholder you need to guess. order_status then advances from created to accepted after roughly 20 seconds, and to delivered after roughly 60 seconds, simulated, no real letter goes out and nothing is charged. Poll order_status with the returned orderId to watch it move. The full parameter reference lives at /en/developers/tools, every error code (including SENDER_PFLICHTANGABEN_INCOMPLETE from Step 2) is listed at /en/developers/errors.

   // 1) Check the connection and token
   mcp_health({})
   
   // 2) Send a test letter (0 cents, no real letter)
   order_send({
     "clientOrderId": "sandbox-quickstart-001",
     "subject": "Test letter from the sandbox",
     "content": "This is a test letter from the FrankKi sandbox. No paper, no cost.",
     "recipientName": "Max Mustermann",
     "recipientStreet": "Musterstraße",
     "recipientHouseNumber": "1",
     "recipientZip": "10115",
     "recipientCity": "Berlin"
   })

See the Conventions panel →