FrankKi MCP

Hosted, remote MCP server. Nothing to install, nothing to self-host. Point your agent at https://mcp.frankki.app (remote, streamable-http, OAuth 2.1 or API key). This repository is the public manifest, documentation and changelog for that server; the server itself is closed-source and runs on our own infrastructure, which is why there is no src/ directory here.

Physical mail for AI agents. With one tool call, FrankKi MCP lets an agent send a real, printed letter to a physical address anywhere in the world. Compose, price, send, and track. The document is printed, franked, and delivered by postal partners worldwide.

This is the official Model Context Protocol (MCP) server for FrankKi. It is built for B2B and developer use: give your agents, backends, and automated workflows the ability to put real letters in the mail, at scale, worldwide.

Website: frankki.app · MCP for humans and agents: frankki.app/mcp (English: frankki.app/en/mcp)

Contents

• What is FrankKi MCP?
• Why physical mail via MCP?
• What your agent can do
• Quick start for humans
• Quick start for AI agents
• Authentication
• Wallet and pricing
• Safety and human-in-the-loop
• Sandbox
• Compliance
• How a send actually works
• Discovery and server manifest
• Documentation
• FAQ
• Links

What is FrankKi MCP?

FrankKi MCP is the agent-native interface to FrankKi's physical mail infrastructure. FrankKi composes, prints, and physically mails letters. This server exposes that capability to software: your model drafts a letter and sends it, and a real document arrives at the recipient's address.

Delivery is worldwide, handled by our postal partners in each destination country. It is primarily a B2B and developer product: if you are building an assistant, an ops automation, or a backend that needs to produce and dispatch physical correspondence, this is your physical-output layer.

Why physical mail via MCP?

Some things still have to arrive on paper: formal and legal notices, transactional and compliance mail, contract confirmations, dunning and reminders, customer onboarding, official correspondence. These workflows usually dead-end at "now a human prints this and walks to a postbox." FrankKi MCP removes that step. The same agent that drafts the letter can send it, worldwide, and track delivery.

Typical uses:

• Dunning and payment reminders
• Cancellations, terminations, objections, and other formal notices
• Contract and order confirmations
• Customer and account notifications
• Onboarding and welcome letters
• Any workflow whose last step must be a physical letter

What your agent can do

The server exposes a focused, scoped tool set. The core send flow:

Beyond the core flow there are tools for attachments, letterheads and signatures, sender profiles, send presets, scheduled sends, order cancellation, posting receipts (Einlieferungsbeleg), client (Mandanten) lookups, and GoBD/DATEV archive exports. The full list with scopes and side effects: docs/tools.md. The authoritative, versioned list is always what the server returns from the MCP tools/list method.

Composition is text-first: you provide the letter content and the recipient, and FrankKi produces the correctly laid-out document (DIN 5008 by default). Attachments are supported. Sending a pre-rendered arbitrary PDF is intentionally not part of the platform.

Quick start for humans

You do not clone or self-host anything. The FrankKi MCP server is hosted. You point your MCP client at it and authenticate.

1. Get access. Create a partner account and issue a key from the dashboard at frankki.app/mcp. Fund your wallet, or use the sandbox first (no real mail).

2a. Claude Desktop and clients with native remote support. Add a custom connector pointing at the endpoint. OAuth runs in your browser on first use:

{
  "mcpServers": {
    "frankki": {
      "url": "https://mcp.frankki.app"
    }
  }
}

2b. Clients that only speak stdio (older Claude Desktop, some Cursor setups). Bridge with mcp-remote:

{
  "mcpServers": {
    "frankki": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.frankki.app"]
    }
  }
}

2c. Headless with an API key (no interactive browser). Pass the key as a bearer header:

{
  "mcpServers": {
    "frankki": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://mcp.frankki.app",
        "--header", "Authorization: Bearer ${FRANKKI_API_KEY}"
      ]
    }
  }
}

2d. Claude Code. One command:

claude mcp add --transport http frankki https://mcp.frankki.app

Restart the client, and your model can now send letters. Ask it something like: "Send this payment reminder to the address on file, but show me the price first."

Step-by-step guides for Cursor, VS Code, Windsurf, Zed, the OpenAI Agents SDK, and LangChain: docs/clients.md.

Quick start for AI agents

The server is standard streamable HTTP MCP. Discovery, endpoint, and auth in one place:

• Endpoint: https://mcp.frankki.app
• Registry name: app.frankki/letters (published in the Official MCP Registry, version 1.0.0)
• Auth metadata: https://mcp.frankki.app/.well-known/oauth-authorization-server (OAuth 2.1, dynamic client registration) or a static bearer API key
• Machine-readable overview: https://frankki.app/llms.txt

TypeScript

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://mcp.frankki.app"),
  { requestInit: { headers: { Authorization: `Bearer ${process.env.FRANKKI_API_KEY}` } } }
);

const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(transport);

const { tools } = await client.listTools();
console.log(tools.map((t) => t.name));

const price = await client.callTool({
  name: "shipping_quote",
  arguments: { recipientCountry: "US", deliveryType: "standard" },
});

Python

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

url = "https://mcp.frankki.app"
headers = {"Authorization": f"Bearer {FRANKKI_API_KEY}"}

async with streamablehttp_client(url, headers=headers) as (read, write, _):
    async with ClientSession(read, write) as session:
        await session.initialize()
        tools = await session.list_tools()
        print([t.name for t in tools.tools])

Authentication

Two modes, pick per client:

• OAuth 2.1 for interactive clients (Claude Desktop, IDEs). The consent screen shows what the agent is allowed to do, and read-only scopes are granted by default. Best when an end user connects their own FrankKi account.
• API key (bearer token) for headless agents, servers, and CI. Issue and rotate keys in the dashboard. Each key can carry a spending limit and an allowed-tools scope, so a key that may look up prices does not have to be a key that may spend money.

Wallet and pricing

FrankKi runs on a prepaid wallet. You top it up (via Stripe), and each send draws from the balance. No surprise post-paid invoices, and an out-of-credit agent simply cannot spend.

• Pricing depends on the destination country. A domestic letter within Germany starts at 3,49 EUR; international sends are priced per destination.
• Registered mail and other service levels are available where the destination supports them.
• Volume tiers (Staffelpreise) reduce the per-letter price at scale.