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 de acordo com 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 para um envio a 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 massa: uma chamada, muitos destinatários com campos de mesclagem	gasta dinheiro, envia papel
`approval_submit`	Roteia 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 do 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 é executado 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 é HTTP streamable padrão do MCP. Descoberta, endpoint e autenticação em um só lugar:

Endpoint: https://mcp.frankki.app
Nome no registro: app.frankki/letters (publicado no Registro Oficial do MCP, 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 pode 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.
Registrado 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 atualizado 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.
Aprovação antes do despacho. Os envios entram na fila de aprovação. O usuário decide no portal autenticado por meio do link de aprovação retornado. O endurecimento OAuth preparado permite aprovação do agente somente após uma concessão separada e explícita de autoaprovação. Veja o contrato de autorização e o status de lançamento.
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 produção, mas nenhum papel é impresso e nenhuma cobrança é feita. Construa e demonstre sua integração de ponta a ponta e depois troque para 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.
Exportações DATEV e DMS genéricas 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 enfileira a carta para aprovação. Mostre o link de aprovação ao usuário; a execução segue uma decisão autorizada.
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 Registro Oficial do MCP, nome app.frankki/letters) e um llms.txt de 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

Documento	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 o 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 a passar por uma fila de aprovação humana, e ferramentas destrutivas são claramente anotadas. Comece na 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. Veja 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 correio físico para software, para que seus agentes e fluxos de trabalho possam enviar cartas reais para todo o mundo sem nunca tocar em uma impressora.