Canonical setup for AI agents

Connect an agent to FrankKi safely

Start in the sandbox when your account has access. Validate the address, inspect the rendered letter, quote the exact cost, and require a human decision before physical mail can leave.

Five-minute sandbox-first connection check

Create the account and complete the first onboarding step before timing the connection check. Sandbox access is account-scoped, not assumed. In the dashboard token area, create a Test-Token only when the Probe access tab is available. The raw token is shown once.

Connect the Test-Token to https://mcp.frankki.app, call mcp_health, and verify that the session reports test mode and sandbox capability. A sandbox send uses zero cents, test storage, watermarked PDFs, simulated status, and no postal-provider call. If those capabilities are absent, stop. Do not fall through to production.

Authentication: interactive or headless

Interactive clients use the OAuth 2.1 source contract with PKCE and dynamic client registration at the remote MCP endpoint. Current production availability of OAuth and DCR is not independently confirmed. If browser authorization is unavailable, use an explicitly scoped API key instead of claiming OAuth succeeded.

Headless agents use a bearer API key issued at https://frankki.app/dashboard/tokens. Store it in a secret manager and send Authorization: Bearer <FRANKKI_API_KEY>. Grant only required scopes and set a conservative daily spending cap. Never place a key in a prompt, repository, or log.

Safe send workflow

The required order is address_validate, letter_create_draft, letter_preview, shipping_quote, dry-run order_send, explicit human approval, live order_send, approval_decide when queued, then order_status. Use approvalMode:"review" on a live send when human review is required. Sandbox sends force the sandbox path and do not demonstrate the live approval queue.

Set maxCostEuros on every order_send. Echo priceVersion and quotedUnitPriceCents from shipping_quote when available so a changed price fails with PRICE_CHANGED before any debit. Use deterministic clientLetterId and clientOrderId values. Replays use the same key and payload; IDEMPOTENCY_CONFLICT means the key was reused for different content.

Cancellation and irreversible states

A chat approval has a ten-minute grace window when the approval result returns dispatchAt and cancellable:true. Call order_cancel immediately when the human says stop. Cancellation is never guaranteed: order_status is authoritative, and order_cancel refuses after the print cutoff.

Once printing starts, the physical letter cannot be recalled. A successful pre-print cancellation credits the closed-loop wallet rather than refunding a payment card. Never describe a submitted, approved, or processing letter as cancelled until the tool confirms it.

Complete safe-send prompt

Give this policy to an agent as a system or workflow instruction. Replace no safety step with model judgment.

Use FrankKi conservatively.

1. Start with mcp_health. For a rehearsal, continue only when the response confirms sandbox capability and a test token. Never turn a failed sandbox check into a live send.
2. Call address_validate with the complete recipient address. Stop on ADDRESS_INVALID or COUNTRY_NOT_SUPPORTED. Never guess or silently repair an address.
3. Create the draft with letter_create_draft and a stable clientLetterId. Inspect its rendered pages, then call letter_preview for the final letterId.
4. Call shipping_quote with the preview's page count, color, destination, and delivery type. Treat the returned price and priceVersion as authoritative.
5. Show the human the recipient, subject, rendered preview, delivery type, and exact total. Ask for a maximum cost in euros. Do not infer approval from the original request.
6. Rehearse order_send with dryRun:true, approvalMode:"review", maxCostEuros set to the human's cap, the quote's priceVersion and quotedUnitPriceCents, and a stable clientOrderId. Resolve every returned error before continuing.
7. Ask: "Approve this exact preview for [exact price] via [delivery type], with a maximum cost of [maxCostEuros]?" Continue only after an explicit yes.
8. Call order_send again with the identical payload and clientOrderId, changing only dryRun to false. A retry must reuse both the same key and the same payload. A new intent needs a new key.
9. If an approvalId is returned, show the frozen preview, exact price, and delivery type again. Call approval_decide with decision:"approve" and user_saw_preview:true only after the human explicitly approves. Rejection is always allowed.
10. Report approvalId or orderId, status, dispatchAt, and cancellable exactly as returned. If the human says stop, call order_cancel immediately. Never promise cancellation: once printing starts, physical mail cannot be recalled.

References

Machine-readable twin: agent-onboarding.md