Model Context Protocol

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 Code
claude mcp add --transport http briefsenden https://www.briefsenden.com/mcp

Mit 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.

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_…"

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
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 Coins

    Ein PDF drucken und als Brief über die Deutsche Post versenden, bezahlt mit Coins aus dem Guthaben

    Scope: letters:write · Briefe versenden und Serienbriefe abbrechen

  • get_letter

    nur lesen

    Einen Brief mit Status, Statusverlauf, Kosten und bei Einschreiben der Sendungsnummer abrufen

    Scope: letters:read · Briefe und Serienbriefe ansehen

  • list_letters

    nur lesen

    Briefe des Kontos auflisten, neueste zuerst; filterbar nach Status (status, z. B. SENT,ERROR) und Suchtext für Empfänger, PLZ oder Ort

    Scope: letters:read · Briefe und Serienbriefe ansehen

  • estimate_cost

    nur lesen

    Kosten 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ätzen

  • get_balance

    nur lesen

    Coin-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.

ParameterBeschreibung
pdfUrlÖffentliche HTTP(S)-Adresse des PDFs, höchstens 20 MB
pdfBase64Das PDF als Base64-Text, wenn es keine URL gibt
addressInPdftrue: Empfängeradresse aus dem Anschriftfeld nach DIN 5008 im PDF lesen. Das Land kommt dann aus der letzten Zeile der Anschrift, recipientCountry gilt nicht.
recipientLine1Name oder Firma des Empfängers; Pflicht ohne addressInPdf
recipientLine2Straße und Hausnummer, optional
recipientZipPostleitzahl; Pflicht für Empfänger in Deutschland
recipientCityOrt; Pflicht ohne addressInPdf
recipientCountryLand als ISO-3166-Code, Standard DE
colorBW (Standard) oder COLOR
duplexSIMPLEX (Standard) oder DUPLEX; Einschreiben nur mit SIMPLEX
registeredLetterEinschreiben, nur innerhalb Deutschlands: EINSCHREIBEN, EINSCHREIBEN_EINWURF oder EINSCHREIBEN_RÜCKSCHEIN
fitToA4true: Seiten, die nicht A4 sind, auf A4 skalieren. Ohne diese Angabe lehnt der Server solche PDFs ab.
senderProfileIdID eines Absenderprofils des Kontos, mit seinem Deckblatt
senderName, senderStreet, senderZip, senderCityAbsender ohne Profil, nur alle vier gemeinsam
idempotencyKeySchlü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.

Kostenloser Testmodus – keine Kreditkarte nötig

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.

Keine Grundgebühr Keine Mindestmenge Pay-per-Letter