Model Context Protocol

MCP server for sending letters

With the MCP server of briefsenden.com, AI assistants and agents send PDFs as real letters through Deutsche Post: send a letter, check its status, estimate costs and check the balance. The Model Context Protocol (MCP) is an open standard that lets assistants use external tools. You only enter an address and sign in with OAuth 2.0 or an API key.

At a glance

What your client needs to connect

Address
https://www.briefsenden.com/mcp
Transport, without sessions
Streamable HTTP
Authentication
OAuth 2.0 · X-Api-Key
Server card
/.well-known/mcp/server-card.json

Connect

Two ways to connect, plus a test without a client – choose one

With OAuth 2.0

If your client supports OAuth 2.0, you only enter the address. From the first 401 response the client finds the metadata at /.well-known/oauth-protected-resource/mcp, registers itself and opens the sign-in at briefsenden.com. There you see which permissions the assistant receives, and you consent.

Claude Code
claude mcp add --transport http briefsenden https://www.briefsenden.com/mcp

With an API key

For your own account, an API key from the dashboard in the X-Api-Key header is enough. Start with a test key (bv_test_…): letters are then not printed and cost no Coins. Clients with a configuration file often expect the JSON form; the field names may differ from client to client. If an API key is set, it applies, and OAuth is not used.

JSON
{
  "mcpServers": {
    "briefsenden": {
      "type": "http",
      "url": "https://www.briefsenden.com/mcp",
      "headers": { "X-Api-Key": "bv_test_…" }
    }
  }
}
Claude Code
claude mcp add --transport http briefsenden https://www.briefsenden.com/mcp \
  --header "X-Api-Key: bv_test_…"

Try it without a client

The server works without sessions: every request stands on its own, and a tool can be called directly. It answers with a JSON-RPC message, either as JSON or as a server-sent event; this is why Accept names both formats. tools/list returns all tools with their parameters.

cURL
curl -X POST https://www.briefsenden.com/mcp \
  -H "X-Api-Key: bv_test_…" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call",
       "params": {"name": "get_balance", "arguments": {}}}'

# result
{ "content": [{ "type": "text",
  "text": "{\"coins\":1200,\"reserved\":90,\"available\":1110}" }] }

Tools

What the assistant can do with your account

Every tool calls the same endpoint as the REST API: same checks, same dispatch, same test mode. Field names and values of the results match the API under /api/v1; estimate_cost also returns its result as structuredContent.

  • send_letter

    prints and sends, costs Coins

    Print a PDF and send it as a letter through Deutsche Post, paid for with Coins from the balance

    Scope: letters:write · Send letters and cancel mail merges

  • get_letter

    read only

    Get one letter with its status, status history, cost and, for registered mail, the tracking number

    Scope: letters:read · View letters and mail merges

  • list_letters

    read only

    List the letters of the account, newest first; filter by status (status, e.g. SENT,ERROR) and search text for recipient, postcode or city

    Scope: letters:read · View letters and mail merges

  • estimate_cost

    read only

    Estimate the cost of one letter in euro cents and Coins, by pages, colour, duplex, registered mail and country. Sends nothing.

    Scope: balance:read · View the balance and estimate costs

  • get_balance

    read only

    Coin balance of the account: total, reserved for letters in progress, and available

    Scope: balance:read · View the balance and estimate costs

Parameters of send_letter

The PDF comes as pdfUrl or pdfBase64, in A4 format. You give the recipient address in fields or have it read from the address window of the PDF with addressInPdf. Without sender details, the default profile of the account applies, including its cover page; a cover page is added as an extra page and costs too, so count it in pages for estimate_cost.

ParameterDescription
pdfUrlPublic HTTP(S) address of the PDF, at most 20 MB
pdfBase64The PDF as Base64 text, if there is no URL
addressInPdftrue: read the recipient address from the DIN 5008 address window of the PDF. The country then comes from the last line of the address, and recipientCountry does not apply.
recipientLine1Name or company of the recipient; required without addressInPdf
recipientLine2Street and house number, optional
recipientZipPostcode; required for recipients in Germany
recipientCityCity; required without addressInPdf
recipientCountryCountry as ISO 3166 code, default DE
colorBW (default) or COLOR
duplexSIMPLEX (default) or DUPLEX; registered mail only with SIMPLEX
registeredLetterRegistered mail, within Germany only: EINSCHREIBEN, EINSCHREIBEN_EINWURF or EINSCHREIBEN_RÜCKSCHEIN
fitToA4true: scale pages that are not A4 to A4. Without it, the server rejects such PDFs.
senderProfileIdID of a sender profile of the account, with its cover page
senderName, senderStreet, senderZip, senderCitySender without a profile, only all four together
idempotencyKeyKey against duplicate letters, see below

Permissions

With OAuth, the server initially suggests only balance:read and letters:read. If your client follows the suggestion, the assistant can at first only read and estimate costs; on the first send_letter the server answers with 403 (insufficient_scope), and the client requests letters:write. If the client asks for all permissions right away, the first grant already includes sending. Either way, the consent page shows you which permissions the assistant receives before you agree. A token is valid for the MCP server and for the REST API under /api/v1. You can revoke access at any time under Settings → Developer → Connected apps. More on OAuth 2.0

Test mode and costs

A test key (bv_test_…) always creates test letters: not printed, not sent, no Coins. With a live key or with OAuth, letters follow the test mode of the account: if it is on, they are test letters too; otherwise every letter is printed, sent and paid for with Coins from the balance. This is why send_letter is marked as destructive (destructiveHint), and its description tells the assistant to confirm recipient and document with you first.

Avoiding duplicate letters

Pass an idempotencyKey to send_letter (up to 64 letters, digits and hyphens). Another call with the same key within 24 hours returns the first letter instead of sending a second one; the key applies per API key or per OAuth grant. It does not lock a call that is still running, though: after a timeout, first check with list_letters whether the letter already exists before the assistant tries again.

Limits and errors

The MCP server shares the rate limit with the REST API: one request every 500 ms per API key or per OAuth grant, up to 10 more wait in the order they arrive, beyond that the server answers with 429. Business errors such as too little balance, a missing postcode, a file that is not a PDF or an unknown value for color come back as a tool result with isError: true and a readable message, so the assistant can explain or correct them.

Endpoints, webhooks and error format of the REST API: go to the API documentation.

Free test mode – no credit card needed

Connect your assistant

Create a free account, create a test key and let your AI assistant send its first letter in test mode, without anything being printed.

No base fee No minimum order Pay per letter