For developers and AI agents
FrankKi for developers
Connect your client
Claude, Claude Desktop, Claude Code and ChatGPT sign in over OAuth. You add the URL, sign in to FrankKi in the browser window or create your account there, and allow access. You only need a production token for scripts, servers and clients without a sign-in window. There is no sandbox for regular accounts. To test for free, use dryRun: the same checks and the same price, nothing printed and nothing charged.
Open the Claude Desktop QuickstartWhat FrankKi MCP is: the MCP server for physical mail
FrankKi is the agentic layer of letters: physical mail for AI agents and people. FrankKi MCP is the live physical mail API for AI agents, a hosted Model Context Protocol server at https://mcp.frankki.app that lets an agent draft, price, send and track real physical letters through a One-Shot-Send call instead of a multi-step form. The official MCP Registry name is app.frankki/letters. The same partner interface is also available as a REST variant. Delivery is worldwide: local postal tariffs across DACH and several European countries, DHL to the rest of the world. For mail that has to survive a compliance review you get Einschreiben (registered mail) with Einlieferungsbeleg (proof of posting), Mandanten (client matters) separation and approval flows with a human decision before a letter leaves. You pay per letter, with no subscription, from a closed-loop wallet: top up once, every send debits it to the cent, with no per-letter card prompt.
Before you start
- Step 0
Create your account
Create it in the sign-in window when you connect Claude or ChatGPT, or beforehand at /dashboard/registrieren. It is free, needs no invitation and no company.
- Step 1
Choose your sign-in
Claude, Claude Desktop, Claude Code and ChatGPT: add https://mcp.frankki.app and sign in over OAuth 2.1 (PKCE, Dynamic Client Registration). Scripts, servers, Cursor and other clients without a sign-in window: create a production token under /dashboard/tokens with only the rights you need. It is shown once. Send it as Authorization: Bearer.
- Step 2
Sender profile and AVV
Complete the sender profile and sign the data processing agreement. dryRun checks both, so do this before the first rehearsal. Top up your wallet (from EUR 10) before the first real send.
- Step 3
Rehearse with dryRun first
Call mcp_health, then run order_send with dryRun:true. The rehearsal is free and returns the price and page 1 as an image. A real send without dryRun waits for approval in the dashboard.
Quickstart per client
Claude Desktop
Add a connector, choose "Sign in now", sign in to FrankKi. No token needed.
Claude Code
claude mcp add --transport http frankki https://mcp.frankki.app, then /mcp to sign in.
ChatGPT
Add it as a custom MCP server with OAuth, where your ChatGPT plan allows that.
Cursor
Production token from /dashboard/tokens as the Authorization header in .cursor/mcp.json.
More reference
Safe agent onboarding
The flow from sign-in to approval: OAuth or API key, address validation, preview, cost cap, approval, idempotency and cancellation. You rehearse with dryRun.
Physical mail with human approval
Frozen-preview decisions, approval tool contracts, independent controls, cancellation, and legal boundaries.
Sandbox and spending limits
Account-scoped test capability, minimum scopes, quote checks, per-send ceilings, daily caps, wallet controls, and fail-closed retries.
Worldwide destination and quoting guide
Conditional destination support, standard versus tracked or registered products, authoritative quotes, and unavailable outcomes.
Tool reference
Every tool with name, description and fields, generated straight from the real registry.
Codex setup
Streamable HTTP configuration, bearer-token environment variable, tool allowlist, and write approvals.
n8n setup and transport status
Manual workflow and human-review design, with the current SSE-versus-Streamable-HTTP compatibility gap stated explicitly.
OpenAI Agents SDK setup
MCPServerStreamableHttp configuration, narrow tool filtering, and an external approval boundary.
LangChain setup
langchain-mcp-adapters connection and a LangGraph interrupt before any physical-mail submission.
CrewAI setup
Structured MCPServerHTTP configuration with bearer headers and a conservative tool allowlist.
Error catalog
Every error code with its meaning, recovery class and fix link.
Conventions
ISO-8601, cent amounts, idempotency and dryRun, in one place.
Letter design
Reusable letterhead, info block, footer, QR code and fold marks: save, preview and apply per letter with designId and reference.
Structured letter content (blocks)
Build invoices, tables and styled letters with blocks and styleDefs instead of plain text: vocabulary, limits and the letter_preview crafting loop.
E-invoicing: ZUGFeRD and XRechnung
How a sent invoice yields a ZUGFeRD PDF/A-3 with EN 16931 XML and a standalone XRechnung: the flow, the file, the blocked reasons and the download-only scope guard.
Transcript: Complete letter job
The whole job in one conversation: quote, draft, attachment, send into the approval queue, human approval, tracking, cancel and fix.
Webhooks (preview)
Planned event types and signature contract, not live yet.
Changelog
API version state and upcoming changes.
Trust and live status
Machine-readable service facts and the current operational status of the partner interface are publicly available at all times, no login needed.