MCP-Server für den Briefversand
Über den MCP-Server von briefsenden.com versenden KI-Assistenten und Agenten PDFs als echte Briefe über die Deutsche Post: Brief senden, Status abfragen, Kosten schätzen und Guthaben prüfen. Das Model Context Protocol (MCP) ist ein offener Standard, über den Assistenten externe Werkzeuge nutzen. Sie tragen nur eine Adresse ein und melden sich per OAuth 2.0 oder API-Key an.
Auf einen Blick
Was Ihr Client zum Verbinden braucht
- Adresse
- https://www.briefsenden.com/mcp
- Transport, ohne Sitzungen
- Streamable HTTP
- Anmeldung
- OAuth 2.0 · X-Api-Key
- Server Card
- /.well-known/mcp/server-card.json
Verbinden
Zwei Wege zum Verbinden, dazu ein Test ohne Client – wählen Sie einen
Mit OAuth 2.0
Unterstützt Ihr Client OAuth 2.0, tragen Sie nur die Adresse ein. Der Client findet über die erste 401-Antwort die Metadaten unter /.well-known/oauth-protected-resource/mcp, registriert sich selbst und öffnet die Anmeldung bei briefsenden.com. Dort sehen Sie, welche Berechtigungen der Assistent erhält, und stimmen zu.
claude mcp add --transport http briefsenden https://www.briefsenden.com/mcpMit API-Key
Für Ihr eigenes Konto genügt ein API-Key aus dem Dashboard im Header X-Api-Key. Beginnen Sie mit einem Test-Key (bv_test_…): Briefe werden dann nicht gedruckt und kosten keine Coins. Clients mit Konfigurationsdatei erwarten oft die JSON-Form; die Feldnamen können je nach Client abweichen. Ist ein API-Key eingetragen, gilt er, und OAuth wird nicht genutzt.
{
"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_…"Ohne Client ausprobieren
Der Server arbeitet ohne Sitzungen: Jede Anfrage steht für sich, ein Tool lässt sich direkt aufrufen. Er antwortet mit einer JSON-RPC-Nachricht, als JSON oder als Server-Sent Event; deshalb nennt Accept beide Formate. tools/list liefert alle Tools mit ihren Parametern.
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
Was der Assistent mit Ihrem Konto tun kann
Jedes Tool ruft denselben Endpunkt wie die REST-API auf: gleiche Prüfungen, gleicher Versand, gleicher Testmodus. Feldnamen und Werte der Ergebnisse entsprechen der API unter /api/v1; estimate_cost liefert sein Ergebnis zusätzlich als structuredContent.
send_letter
druckt und versendet, kostet CoinsEin PDF drucken und als Brief über die Deutsche Post versenden, bezahlt mit Coins aus dem Guthaben
Scope:
letters:write· Briefe versenden und Serienbriefe abbrechenget_letter
nur lesenEinen Brief mit Status, Statusverlauf, Kosten und bei Einschreiben der Sendungsnummer abrufen
Scope:
letters:read· Briefe und Serienbriefe ansehenlist_letters
nur lesenBriefe des Kontos auflisten, neueste zuerst; filterbar nach Status (
status, z. B.SENT,ERROR) und Suchtext für Empfänger, PLZ oder OrtScope:
letters:read· Briefe und Serienbriefe ansehenestimate_cost
nur lesenKosten eines Briefs in Euro-Cent und Coins schätzen, nach Seiten, Farbe, Duplex, Einschreiben und Land. Versendet nichts.
Scope:
balance:read· Guthaben ansehen und Kosten schätzenget_balance
nur lesenCoin-Guthaben des Kontos: gesamt, für laufende Briefe reserviert und verfügbar
Scope:
balance:read· Guthaben ansehen und Kosten schätzen
Parameter von send_letter
Das PDF kommt als pdfUrl oder pdfBase64, im Format A4. Die Empfängeradresse geben Sie in Feldern an oder lassen sie mit addressInPdf aus dem Anschriftfeld des PDFs lesen. Ohne Angabe zum Absender gilt das Standardprofil des Kontos samt Deckblatt; ein Deckblatt kommt als zusätzliche Seite hinzu und kostet mit, zählen Sie es bei estimate_cost unter pages mit.
| Parameter | Beschreibung |
|---|---|
| pdfUrl | Öffentliche HTTP(S)-Adresse des PDFs, höchstens 20 MB |
| pdfBase64 | Das PDF als Base64-Text, wenn es keine URL gibt |
| addressInPdf | true: Empfängeradresse aus dem Anschriftfeld nach DIN 5008 im PDF lesen. Das Land kommt dann aus der letzten Zeile der Anschrift, recipientCountry gilt nicht. |
| recipientLine1 | Name oder Firma des Empfängers; Pflicht ohne addressInPdf |
| recipientLine2 | Straße und Hausnummer, optional |
| recipientZip | Postleitzahl; Pflicht für Empfänger in Deutschland |
| recipientCity | Ort; Pflicht ohne addressInPdf |
| recipientCountry | Land als ISO-3166-Code, Standard DE |
| color | BW (Standard) oder COLOR |
| duplex | SIMPLEX (Standard) oder DUPLEX; Einschreiben nur mit SIMPLEX |
| registeredLetter | Einschreiben, nur innerhalb Deutschlands: EINSCHREIBEN, EINSCHREIBEN_EINWURF oder EINSCHREIBEN_RÜCKSCHEIN |
| fitToA4 | true: Seiten, die nicht A4 sind, auf A4 skalieren. Ohne diese Angabe lehnt der Server solche PDFs ab. |
| senderProfileId | ID eines Absenderprofils des Kontos, mit seinem Deckblatt |
| senderName, senderStreet, senderZip, senderCity | Absender ohne Profil, nur alle vier gemeinsam |
| idempotencyKey | Schlüssel gegen doppelten Versand, siehe unten |
Berechtigungen
Mit OAuth schlägt der Server zum Einstieg nur balance:read und letters:read vor. Übernimmt Ihr Client den Vorschlag, kann der Assistent zunächst nur lesen und Kosten schätzen; beim ersten send_letter antwortet der Server mit 403 (insufficient_scope), und der Client fordert letters:write nach. Fragt der Client gleich alle Berechtigungen an, enthält schon die erste Freigabe den Versand. Welche Berechtigungen der Assistent erhält, zeigt Ihnen in jedem Fall die Zustimmungsseite, bevor Sie zustimmen. Ein Token gilt für den MCP-Server und die REST-API unter /api/v1. Widerrufen können Sie den Zugriff jederzeit unter Einstellungen → Entwickler → Verbundene Apps. Mehr zu OAuth 2.0
Testmodus und Kosten
Ein Test-Key (bv_test_…) erzeugt immer Testbriefe: nicht gedruckt, nicht versendet, ohne Coins. Mit einem Live-Key oder mit OAuth folgen Briefe dem Testmodus des Kontos: Ist er eingeschaltet, entstehen ebenfalls Testbriefe, sonst wird jeder Brief gedruckt, versendet und mit Coins aus dem Guthaben bezahlt. send_letter ist deshalb als destruktiv markiert (destructiveHint), und seine Beschreibung weist den Assistenten an, Empfänger und Dokument vorher mit Ihnen zu bestätigen.
Doppelten Versand vermeiden
Geben Sie bei send_letter einen idempotencyKey mit (bis zu 64 Buchstaben, Ziffern und Bindestriche). Ein erneuter Aufruf mit demselben Schlüssel liefert innerhalb von 24 Stunden den ersten Brief zurück, statt einen zweiten zu versenden; der Schlüssel gilt je API-Key bzw. je OAuth-Freigabe. Er sperrt aber keinen Aufruf, der noch läuft: Prüfen Sie nach einer Zeitüberschreitung zuerst mit list_letters, ob der Brief schon angelegt ist, bevor der Assistent es erneut versucht.
Limits und Fehler
Der MCP-Server teilt sich das Rate Limit mit der REST-API: ein Request alle 500 ms je API-Key bzw. je OAuth-Freigabe, bis zu 10 weitere warten in der Reihenfolge ihres Eingangs, darüber antwortet der Server mit 429. Fachliche Fehler wie zu wenig Guthaben, eine fehlende Postleitzahl, eine Datei, die kein PDF ist, oder ein unbekannter Wert für color kommen als Tool-Ergebnis mit isError: true und einer lesbaren Meldung zurück, damit der Assistent sie Ihnen erklären oder korrigieren kann.
Endpunkte, Webhooks und Fehlerformat der REST-API: zur API-Dokumentation.
Assistent verbinden
Erstellen Sie ein kostenloses Konto, legen Sie einen Test-Key an und lassen Sie Ihren KI-Assistenten den ersten Brief im Testmodus versenden, ohne dass etwas gedruckt wird.