Claude Desktop 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 Claude Desktop

   Open the "Test token" tab under /dashboard/tokens in the dashboard and mint a token. It is shown to you once in plain text, copy it right away, you cannot view it again afterwards. Open the connector settings in Claude Desktop and add the FrankKi endpoint with your test token as the Authorization header (config below). Claude Desktop usually offers an OAuth login for connectors, but the FrankKi OAuth connector currently runs LIVE only (Epic 15) and cannot reach a green sandbox send. For the sandbox you paste the test token manually as a header instead, token-paste is the canonical path here.

   {
     "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 →