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 mcp add --transport http briefsenden https://www.briefsenden.com/mcpWith 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.
{
"mcpServers": {
"briefsenden": {
"type": "http",
"url": "https://www.briefsenden.com/mcp",
"headers": { "X-Api-Key": "bv_test_…" }
}
}
}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 -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 CoinsPrint 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 mergesget_letter
read onlyGet one letter with its status, status history, cost and, for registered mail, the tracking number
Scope:
letters:read· View letters and mail mergeslist_letters
read onlyList the letters of the account, newest first; filter by status (
status, e.g.SENT,ERROR) and search text for recipient, postcode or cityScope:
letters:read· View letters and mail mergesestimate_cost
read onlyEstimate 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 costsget_balance
read onlyCoin 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.
| Parameter | Description |
|---|---|
| pdfUrl | Public HTTP(S) address of the PDF, at most 20 MB |
| pdfBase64 | The PDF as Base64 text, if there is no URL |
| addressInPdf | true: 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. |
| recipientLine1 | Name or company of the recipient; required without addressInPdf |
| recipientLine2 | Street and house number, optional |
| recipientZip | Postcode; required for recipients in Germany |
| recipientCity | City; required without addressInPdf |
| recipientCountry | Country as ISO 3166 code, default DE |
| color | BW (default) or COLOR |
| duplex | SIMPLEX (default) or DUPLEX; registered mail only with SIMPLEX |
| registeredLetter | Registered mail, within Germany only: EINSCHREIBEN, EINSCHREIBEN_EINWURF or EINSCHREIBEN_RÜCKSCHEIN |
| fitToA4 | true: scale pages that are not A4 to A4. Without it, the server rejects such PDFs. |
| senderProfileId | ID of a sender profile of the account, with its cover page |
| senderName, senderStreet, senderZip, senderCity | Sender without a profile, only all four together |
| idempotencyKey | Key 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.
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.