For developers and AI agents
FrankKi for developers
Connect to production
The sandbox is currently unavailable. Interactive clients connect over OAuth 2.1 at https://mcp.frankki.app; headless integrations use a scoped production token. Production calls can debit your wallet and mail real letters, so start with dryRun and review every send before executing it.
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
Sign up at /dashboard/registrieren, free and with no invitation. We email you a one-time link, you set your password there and complete the first onboarding step, which takes one to two minutes, with no AVV and no wallet top-up.
- Step 1
Choose your authentication path
Interactive clients (Claude Desktop, ChatGPT, Cursor, VS Code): add https://mcp.frankki.app as a remote MCP server and let the client authenticate itself. OAuth 2.1 with Authorization Code, PKCE (S256) and Dynamic Client Registration (RFC 7591) is live in production, verified 2026-08-13 against https://mcp.frankki.app/.well-known/oauth-authorization-server. Headless and server-side integrations: open /dashboard/tokens and create a production token with only the rights your integration needs. The token is shown once. Store it securely and send it as Authorization: Bearer.
- Step 2
Complete production requirements
Complete the sender profile, data processing agreement and wallet funding before a real send. These are production requirements, not sandbox setup.
- Step 3
Validate with dryRun first
Call mcp_health, then run order_send with dryRun:true. Only remove dryRun when you intend to pay for and mail a real letter.
Quickstart per client
Claude Desktop
Connect over OAuth 2.1 with PKCE and dynamic client registration, or with an explicitly scoped production token, then validate the first send with dryRun.
Claude Code
Connect over OAuth 2.1 with PKCE and dynamic client registration, or with an explicitly scoped production token, then validate the first send with dryRun.
ChatGPT
Connect over OAuth 2.1 with PKCE and dynamic client registration, or with an explicitly scoped production token, then validate the first send with dryRun.
Cursor
Connect over OAuth 2.1 with PKCE and dynamic client registration, or with an explicitly scoped production token, then validate the first send with dryRun.
More reference
Safe agent onboarding
The canonical sandbox-first workflow with OAuth, API keys, address validation, preview, cost cap, approval, idempotency, and cancellation.
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.