FrankKi

Agentes enviam cartas impressas reais para todo o mundo com cotações, prévias, controles de aprovação e rastreamento por meio de um servidor MCP remoto hospedado.

GitHub

Experimente este MCPPatrocinado

Documentação

FrankKi MCP

Servidor MCP remoto e hospedado. Nada para instalar, nada para auto-hospedar. Aponte seu agente para https://mcp.frankki.app (remoto, streamable-http, OAuth 2.1 ou chave de API). Este repositório é o manifesto público, a documentação e o changelog desse servidor; o servidor em si é de código fechado e roda em nossa própria infraestrutura, por isso não há diretório src/ aqui.

Correio físico para agentes de IA. Com uma única chamada de ferramenta, o FrankKi MCP permite que um agente envie uma carta real e impressa para um endereço físico em qualquer lugar do mundo. Componha, precifique, envie e acompanhe. O documento é impresso, selado e entregue por parceiros postais em todo o mundo.

Este é o servidor oficial do Model Context Protocol (MCP) para FrankKi. Ele é construído para uso B2B e para desenvolvedores: dê aos seus agentes, backends e fluxos de trabalho automatizados a capacidade de colocar cartas reais no correio, em escala, em todo o mundo.

Site: frankki.app · MCP para humanos e agentes: frankki.app/mcp (Inglês: frankki.app/en/mcp)

O que é o FrankKi MCP?

O FrankKi MCP é a interface nativa para agentes da infraestrutura de correio físico do FrankKi. O FrankKi compõe, imprime e envia cartas fisicamente. Este servidor expõe essa capacidade ao software: seu modelo redige uma carta e a envia, e um documento real chega ao endereço do destinatário.

A entrega é mundial, feita por nossos parceiros postais em cada país de destino. É principalmente um produto B2B e para desenvolvedores: se você está construindo um assistente, uma automação de operações ou um backend que precisa produzir e despachar correspondência física, esta é sua camada de saída física.

Por que correio físico via MCP?

Algumas coisas ainda precisam chegar em papel: avisos formais e legais, correspondência transacional e de conformidade, confirmações de contrato, cobranças e lembretes, integração de clientes, correspondência oficial. Esses fluxos de trabalho geralmente terminam em "agora um humano imprime isso e vai até uma caixa de correio". O FrankKi MCP remove essa etapa. O mesmo agente que redige a carta pode enviá-la, em todo o mundo, e acompanhar a entrega.

Usos típicos:

Cobranças e lembretes de pagamento
Cancelamentos, rescisões, objeções e outros avisos formais
Confirmações de contrato e pedido
Notificações de clientes e contas
Integração e cartas de boas-vindas
Qualquer fluxo de trabalho cuja última etapa deva ser uma carta física

O que seu agente pode fazer

O servidor expõe um conjunto de ferramentas focado e com escopo definido. O fluxo principal de envio:

Ferramenta	O que faz	Efeito colateral
`address_validate`	Valida um endereço de destinatário conforme as regras postais do país de destino	somente leitura
`address_search_company`	Consulta o endereço postal de uma empresa pelo nome	somente leitura
`template_list`	Navega por modelos de carta reutilizáveis	somente leitura
`letter_create_draft`	Redige uma carta formatada profissionalmente a partir de texto simples e um destinatário, retorna uma prévia	cria um rascunho, sem envio
`shipping_quote`	Obtém o preço exato de um envio para um destino específico antes de confirmar	somente leitura
`wallet_balance`	Lê o saldo da carteira pré-paga	somente leitura
`order_send`	Envia uma carta física, cobra da carteira; suporta um limite de `maxCostEuros`	gasta dinheiro, envia papel
`order_send_batch`	Envio em lote: uma chamada, muitos destinatários com campos de mesclagem	gasta dinheiro, envia papel
`approval_submit`	Encaminha uma carta para a fila de aprovação de quatro olhos em vez de enviar diretamente	enfileira, sem envio
`order_status`	Acompanha uma carta até impressa, postada e entregue	somente leitura
`wallet_topup_link`	Cria um link seguro de recarga via Stripe	cria um link de pagamento

Além do fluxo principal, há ferramentas para anexos, cabeçalhos e assinaturas, perfis de remetente, predefinições de envio, envios agendados, cancelamento de pedidos, recibos de postagem (Einlieferungsbeleg), consultas de clientes (Mandanten) e exportações de arquivo GoBD/DATEV. A lista completa com escopos e efeitos colaterais: docs/tools.md. A lista autoritativa e versionada é sempre a que o servidor retorna pelo método MCP tools/list.

A composição é baseada em texto: você fornece o conteúdo da carta e o destinatário, e o FrankKi produz o documento corretamente formatado (DIN 5008 por padrão). Anexos são suportados. Enviar um PDF arbitrário pré-renderizado não faz parte da plataforma, intencionalmente.

Início rápido para humanos

Você não clona nem auto-hospeda nada. O servidor MCP do FrankKi é hospedado. Você aponta seu cliente MCP para ele e autentica.

1. Obtenha acesso. Crie uma conta de parceiro e emita uma chave no painel em frankki.app/mcp. Adicione fundos à sua carteira ou use o sandbox primeiro (sem correio real).

2a. Claude Desktop e clientes com suporte remoto nativo. Adicione um conector personalizado apontando para o endpoint. O OAuth roda no seu navegador no primeiro uso:

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

2b. Clientes que só falam stdio (Claude Desktop mais antigo, algumas configurações do Cursor). Faça a ponte com mcp-remote:

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

2c. Sem interface gráfica com chave de API (sem navegador interativo). Passe a chave como cabeçalho bearer:

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

2d. Claude Code. Um comando:

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

Reinicie o cliente, e seu modelo agora pode enviar cartas. Pergunte algo como: "Envie este lembrete de pagamento para o endereço registrado, mas mostre o preço primeiro."

Guias passo a passo para Cursor, VS Code, Windsurf, Zed, OpenAI Agents SDK e LangChain: docs/clients.md.

Início rápido para agentes de IA

O servidor é streamable HTTP MCP padrão. Descoberta, endpoint e autenticação em um só lugar:

Endpoint: https://mcp.frankki.app
Nome no registro: app.frankki/letters (publicado no Official MCP Registry, versão 1.0.0)
Metadados de autenticação: https://mcp.frankki.app/.well-known/oauth-authorization-server (OAuth 2.1, registro dinâmico de clientes) ou uma chave de API bearer estática
Visão geral legível por máquina: 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])

Autenticação

Dois modos, escolha por cliente:

OAuth 2.1 para clientes interativos (Claude Desktop, IDEs). A tela de consentimento mostra o que o agente pode fazer, e escopos somente leitura são concedidos por padrão. Melhor quando um usuário final conecta sua própria conta FrankKi.
Chave de API (token bearer) para agentes sem interface, servidores e CI. Emita e rotacione chaves no painel. Cada chave pode ter um limite de gastos e um escopo de ferramentas permitidas, então uma chave que pode consultar preços não precisa ser uma chave que pode gastar dinheiro.

Carteira e preços

O FrankKi opera com uma carteira pré-paga. Você adiciona fundos (via Stripe), e cada envio debita do saldo. Sem faturas pós-pagas surpresa, e um agente sem crédito simplesmente não consegue gastar.

O preço depende do país de destino. Uma carta doméstica na Alemanha começa em 3,49 EUR; envios internacionais são precificados por destino.
Registro postal e outros níveis de serviço estão disponíveis onde o destino suporta.
Faixas de volume (Staffelpreise) reduzem o preço por carta em escala.

Sempre chame shipping_quote para obter o valor exato e atual antes de order_send. Os preços são autoritativos vindos do servidor, nunca os codifique.

Segurança e aprovação humana

Enviar correio físico é irreversível e custa dinheiro, então a plataforma é cautelosa por padrão:

Anotações honestas. order_send e order_send_batch são anotadas como destrutivas; ferramentas de leitura como somente leitura. Seu agente pode usar isso como base, e order_send aceita um limite de maxCostEuros que aborta o envio se o preço ao vivo excedê-lo.
Fila de aprovação. Encaminhe cartas sensíveis por approval_submit para uma verificação humana de quatro olhos antes de qualquer impressão. Cada decisão é registrada.
Limites de gastos e escopos de ferramentas por chave. Limite o que uma chave automatizada pode gastar e restrinja quais ferramentas ela pode chamar.
Prévia antes de confirmar. letter_create_draft retorna uma prévia renderizada e shipping_quote retorna o custo, para que um agente ou humano possa confirmar antes de order_send.

Sandbox

Teste o fluxo completo sem enviar nada. Solicite uma chave de sandbox no painel, aponte para o mesmo endpoint, e você recebe uma carteira de teste com fundos. Composição, preços e status se comportam como em produção, mas nenhum papel é impresso e nenhuma cobrança é feita. Construa e demonstre sua integração de ponta a ponta e depois troque por uma chave ao vivo.

Conformidade

Nível empresarial e da UE, para equipes que precisam:

Arquivamento em conformidade com GoBD de cada envio, com recibos recuperáveis.
DATEV e exportações genéricas para DMS para contabilidade e gerenciamento de documentos.
DSGVO / GDPR: os dados das cartas são processados na UE.
Plataforma e mensagens disponíveis em inglês e alemão.

Como um envio realmente funciona

Seu agente chama letter_create_draft com o texto e um destinatário. O FrankKi renderiza um documento formatado profissionalmente.
shipping_quote retorna o custo exato para aquele destino. O agente, ou um humano via fila de aprovação, confirma.
order_send debita a carteira pré-paga atomicamente e entrega o trabalho para a execução.
O FrankKi imprime a carta e a entrega para envio mundial via nossos parceiros postais.
O status retorna por order_status: impressa, postada e, onde suportado, entregue. order_einlieferungsbeleg retorna o recibo de postagem.

Descoberta e manifesto do servidor

Para diretórios e registros, este repositório publica server.json (esquema do Official MCP Registry, nome app.frankki/letters) e um llms.txt em nível de repositório para descoberta assistida por IA.

Encontrou este servidor por um diretório MCP? A fonte canônica da verdade é sempre frankki.app/mcp.

Documentação

Doc	Conteúdo
docs/tools.md	Cada ferramenta com escopo, efeitos colaterais, o fluxo canônico de envio e códigos de erro
docs/authentication.md	OAuth 2.1, chaves de API, a lista completa de escopos, configurações recomendadas
docs/clients.md	Configuração para Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Zed, OpenAI Agents SDK, LangChain
docs/use-cases.md	Cobranças, rescisões, correspondência de conformidade, integração, produtos nativos para agentes
examples/	Clientes TypeScript e Python executáveis (sandbox primeiro, envio atrás de uma flag explícita)

FAQ

A carta é realmente impressa e enviada, ou é e-mail? Papel real. Ela é impressa, selada e entregue por parceiros postais. Isso não é e-mail.

Para quais países ela pode entregar? Mundial. Use shipping_quote para confirmar alcance e custo para um destino específico.

Eu hospedo o servidor? Não. O FrankKi hospeda. Este repositório é documentação, server.json e exemplos. Você conecta um cliente ou agente ao endpoint hospedado.

Isso é para consumidores ou empresas? Principalmente uso B2B e para desenvolvedores: agentes, backends e fluxos de trabalho automatizados que precisam despachar correio físico em escala.

E se meu agente sair do controle? Ele não pode gastar além do saldo da carteira ou do limite de gastos de uma chave, cartas sensíveis podem ser forçadas por uma fila de aprovação humana, e ferramentas destrutivas são claramente anotadas. Comece no sandbox. Existe uma API sem MCP? Sim, o FrankKi também expõe uma API REST. O servidor MCP é a porta de entrada nativa para agentes. Consulte frankki.app/mcp.

Links

Página inicial: https://frankki.app
MCP para humanos e agentes: https://frankki.app/mcp · https://frankki.app/en/mcp
Visão geral legível por máquina: https://frankki.app/llms.txt
Endpoint: https://mcp.frankki.app
Nome no registro: app.frankki/letters (publicado no Registro Oficial de MCP, versão 1.0.0)

Construído pela equipe por trás do FrankKi: infraestrutura de correspondência física para software, para que seus agentes e fluxos de trabalho possam enviar cartas reais para todo o mundo sem nunca tocar em uma impressora.