Dispatch MCP Server v0.1

Model Context Protocol Server für die Dispatch API. Ermöglicht Claude und anderen MCP-Clients den direkten Zugriff auf alle API-Funktionen — ohne curl, ohne Code.

Übersicht

Der MCP Server ist ein schlanker HTTP-Proxy: Er nimmt MCP-Tool-Calls entgegen, leitet sie an die Dispatch API weiter und gibt die Antwort zurück. Er läuft auf demselben Server wie die API und kommuniziert intern über 127.0.0.1:3000.

Transport: Streamable HTTP (aktueller MCP-Standard, ersetzt SSE). Stateless — jede Anfrage ist unabhängig, kein Session-State.

Auth: Der MCP Server leitet den Authorization-Header direkt an die API weiter. Auth-Prüfung, Rate Limiting und Domain Enforcement passieren ausschließlich in der API.

Endpoint: https://mcp.dispatch.knerpi.de/mcp

Konfiguration

Den API Key zunächst über POST /keys beantragen (siehe API Docs). Nach Admin-Freigabe wird der Key per Mail zugestellt.

Claude Code

claude mcp add --transport http dispatch https://mcp.dispatch.knerpi.de/mcp \
  --header "Authorization: Bearer dsp_..." \
  --scope user

Mit --scope project wird der Server in .mcp.json im Projektverzeichnis gespeichert und ist für alle Teammitglieder verfügbar. In diesem Fall API Key als Umgebungsvariable referenzieren:

// .mcp.json
{
  "mcpServers": {
    "dispatch": {
      "type": "http",
      "url": "https://mcp.dispatch.knerpi.de/mcp",
      "headers": { "Authorization": "Bearer ${DISPATCH_API_KEY}" }
    }
  }
}

Claude Desktop

Unter Settings → Developer → Edit Config:

{
  "mcpServers": {
    "dispatch": {
      "type": "streamable-http",
      "url": "https://mcp.dispatch.knerpi.de/mcp",
      "headers": {
        "Authorization": "Bearer dsp_..."
      }
    }
  }
}

Der MCP Server validiert den Key nicht selbst — er leitet ihn an die API weiter. Ein ungültiger Key führt zu einem 401-Fehler bei Tool-Aufrufen.

Alle Tools

Tool	Methode	Endpoint	Beschreibung
`send_email`	POST	/emails	E-Mail senden
`list_templates`	GET	/templates	Templates auflisten
`upload_template`	POST	/templates	Template hochladen
`delete_template`	DELETE	/templates/:name	Template löschen
`register_domain`	POST	/domains	Sending Domain registrieren
`list_domains`	GET	/domains	Domains auflisten
`get_domain`	GET	/domains/:id	Domain-Details + DNS-Records
`delete_domain`	DELETE	/domains/:id	Domain löschen
`verify_domain`	POST	/domains/:id/verify	DNS-Verifikation auslösen
`health_check`	GET	/health	Server-Status prüfen

send_email

Sendet eine E-Mail. Entweder html, text oder react_template muss angegeben werden.

Parameter	Typ	Pflicht	Beschreibung
`from`	string	ja	Absender (z.B. `"noreply@example.com"` oder `"Name <noreply@example.com>"`)
`to`	string \| string[]	ja	Empfänger (ein oder mehrere)
`subject`	string	ja	Betreff
`html`	string	ja*	HTML-Body (*mind. eines von html / text / react_template)
`text`	string	nein	Plaintext-Fallback
`react_template`	string	nein	Name eines Server-Templates (statt html)
`react_props`	object	nein	Props für das React-Template
`reply_to`	string	nein	Reply-To-Adresse
`cc`	string \| string[]	nein	CC-Empfänger
`bcc`	string \| string[]	nein	BCC-Empfänger
`headers`	object	nein	Zusätzliche Mail-Header als Key-Value-Objekt

Ohne verifizierte Sending Domains darf nur dispatch.knerpi.de als Absender-Domain verwendet werden. Siehe register_domain.

list_templates

Listet alle auf dem Server verfügbaren React-Email-Templates auf. Keine Parameter.

Gibt ein Objekt mit templates-Array zurück, z.B. { "templates": ["welcome", "bestellung"] }.

upload_template

Lädt ein React-Email-Template (JSX oder TSX) auf den Server. Überschreibt ein bestehendes Template gleichen Namens. Das Template ist sofort nutzbar — kein Neustart erforderlich.

Parameter	Typ	Pflicht	Beschreibung
`name`	string	ja	Template-Name. Nur `a–z A–Z 0–9 - _` erlaubt.
`code`	string	ja	Quellcode des Templates (JSX/TSX)
`ext`	string	nein	`jsx` (Standard) oder `tsx`

delete_template

Löscht ein Template vom Server.

Parameter	Typ	Pflicht	Beschreibung
`name`	string	ja	Name des Templates

register_domain

Registriert eine neue Sending Domain. Generiert ein DKIM-Schlüsselpaar und gibt die erforderlichen DNS-Records zurück (SPF, DKIM, DMARC-Empfehlung). Max. 10 Domains pro Account.

Nach der Registrierung müssen SPF- und DKIM-DNS-Records innerhalb von 72 Stunden gesetzt werden. Ein automatischer Verifikations-Loop prüft alle 15 Minuten. Domains, die nach Ablauf der Deadline nicht verifiziert sind, werden automatisch gelöscht.

Parameter	Typ	Pflicht	Beschreibung
`name`	string	ja	Domain-Name (z.B. `example.com`). Keine öffentlichen Domains (gmail.com etc.).

list_domains

Listet alle registrierten Sending Domains des eigenen Accounts auf. Admins sehen alle Domains aller Accounts. Keine Parameter.

get_domain

Gibt Details einer Domain zurück, inklusive der DNS-Records, die gesetzt werden müssen (SPF, DKIM, DMARC).

Parameter	Typ	Pflicht	Beschreibung
`id`	string	ja	Domain ID (UUID)

delete_domain

Löscht eine registrierte Domain. Mails können danach nicht mehr über diese Domain versendet werden.

Parameter	Typ	Pflicht	Beschreibung
`id`	string	ja	Domain ID (UUID)

verify_domain

Löst eine sofortige DNS-Verifikation aus — prüft ob SPF und DKIM korrekt gesetzt sind. Der automatische Check läuft alle 15 Minuten; dieses Tool ermöglicht eine sofortige Prüfung.

Wenn die Verifikations-Deadline abgelaufen ist, wird die Domain automatisch gelöscht und muss neu registriert werden.

Parameter	Typ	Pflicht	Beschreibung
`id`	string	ja	Domain ID (UUID)

health_check

Prüft den Status der Dispatch API. Keine Parameter, kein Auth erforderlich.

Gibt { "status": "ok" } zurück wenn die API erreichbar ist.

Fehlerbehandlung

API-Fehler werden als MCP-Fehlermeldung zurückgegeben. Der Originaltext aus der API wird durchgeleitet:

HTTP Status	MCP-Fehlermeldung
401	Invalid API key
403	Domain not allowed (Originaltext aus der API)
422	Validierungsfehler (Originaltext aus der API)
429	Rate limit exceeded
500	Internal server error