MCP-Server

SpacePost spricht das Model Context Protocol, sodass KI-Assistenten in deinem Auftrag E-Mails senden und Domains, API-Schlüssel, Webhooks, Zielgruppen, Kontakte, Kampagnen, Sperreinträge und Tenants verwalten können.

Jeder Endpoint in der API-Referenz ist ein MCP-Tool. Die Tools werden aus demselben OpenAPI-Dokument erzeugt wie die Referenz. Bekommt die API eine neue Funktion, bietet der MCP-Server sie automatisch an: Es gibt keine separate Liste, die gepflegt werden muss oder auf die du warten musst.

Du kannst dich auf zwei Arten verbinden:

• Gehostet (empfohlen): https://api.spacepost.dev/mcp, Streamable HTTP, authentifiziert mit deinem API-Schlüssel. Nichts zu installieren.
• Lokal: npx -y @spacepost/mcp, ein stdio-Server, der die API von deinem Rechner aus aufruft. Die Tool-Definitionen sind im Paket enthalten, daher startet er auch offline.

Achtung

Der Assistent handelt mit den Berechtigungen des API-Schlüssels, den du ihm gibst, genau so, als würde er die REST-API aufrufen: dieselben Berechtigungsprüfungen, Rate-Limits, Kontingente und dieselbe Idempotenz. Verwende einen eigenen Schlüssel. Ein sending_access-Schlüssel kann nur send_email und send_batch_emails nutzen: Der gehostete Server listet für einen solchen Schlüssel nur diese beiden auf, und jedes andere Tool antwortet mit restricted_api_key. Füge --read-only (lokal) oder ?read_only=true (gehostet) hinzu, um nur die lesenden Tools bereitzustellen.

Mit dem gehosteten Server verbinden

Sende deinen API-Schlüssel als Bearer-Token: Authorization: Bearer sp_live_....

Claude Code

claude mcp add --transport http spacepost https://api.spacepost.dev/mcp \
  --header "Authorization: Bearer sp_live_YOUR_API_KEY"

Prüfe mit claude mcp list.

Claude Desktop

Claude Desktop startet lokale (stdio-)Server aus claude_desktop_config.json, binde den gehosteten Endpoint deshalb über mcp-remote an (Settings, Developer, Edit Config):

{
  "mcpServers": {
    "spacepost": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://api.spacepost.dev/mcp",
        "--header", "Authorization:${SPACEPOST_AUTH}"
      ],
      "env": { "SPACEPOST_AUTH": "Bearer sp_live_YOUR_API_KEY" }
    }
  }
}

Starte Claude Desktop neu. Oder verwende stattdessen den lokalen Server.

Cursor

Füge in .cursor/mcp.json in deinem Projekt oder global in ~/.cursor/mcp.json Folgendes hinzu:

{
  "mcpServers": {
    "spacepost": {
      "url": "https://api.spacepost.dev/mcp",
      "headers": { "Authorization": "Bearer sp_live_YOUR_API_KEY" }
    }
  }
}

VS Code

Füge in .vscode/mcp.json Folgendes hinzu:

{
  "inputs": [
    { "id": "spacepost-key", "type": "promptString", "description": "SpacePost API key", "password": true }
  ],
  "servers": {
    "spacepost": {
      "type": "http",
      "url": "https://api.spacepost.dev/mcp",
      "headers": { "Authorization": "Bearer ${input:spacepost-key}" }
    }
  }
}

VS Code fragt beim ersten Mal nach dem Schlüssel und hält ihn aus der Datei heraus.

Schränke die Tool-Liste mit Query-Parametern in der URL ein, zum Beispiel https://api.spacepost.dev/mcp?read_only=true&toolsets=emails,domains.

Der gehostete Server ist zustandslos: Jede Anfrage ist unabhängig, daher antworten GET und DELETE auf /mcp mit 405, und es gibt keine Sitzung, die fortgesetzt werden könnte.

Server lokal ausführen

Variable	Erforderlich	Beschreibung
SPACEPOST_API_KEY	Ja	Dein API-Schlüssel
SPACEPOST_BASE_URL	Nein	Alternative API-URL, Standard https://api.spacepost.dev
SPACEPOST_DEFAULT_FROM	Nein	Absender, der verwendet wird, wenn der Assistent send_email ohne from aufruft, zum Beispiel Acme <hello@acme.com>
SPACEPOST_READ_ONLY	Nein	true entspricht --read-only
SPACEPOST_TOOLSETS	Nein	Wie --toolsets, zum Beispiel emails,domains
SPACEPOST_PERMISSION	Nein	Wie --permission; setze sending_access, wenn der Schlüssel nur senden darf

Claude Code

claude mcp add spacepost -e SPACEPOST_API_KEY=sp_live_YOUR_API_KEY -- npx -y @spacepost/mcp

Füge -e SPACEPOST_DEFAULT_FROM="Acme <hello@acme.com>" hinzu, um einen Standard-Absender festzulegen, oder Flags nach dem Paketnamen, etwa npx -y @spacepost/mcp --read-only.

Claude Desktop

{
  "mcpServers": {
    "spacepost": {
      "command": "npx",
      "args": ["-y", "@spacepost/mcp"],
      "env": {
        "SPACEPOST_API_KEY": "sp_live_YOUR_API_KEY",
        "SPACEPOST_DEFAULT_FROM": "Acme <hello@acme.com>"
      }
    }
  }
}

Cursor

{
  "mcpServers": {
    "spacepost": {
      "command": "npx",
      "args": ["-y", "@spacepost/mcp", "--toolsets", "emails,domains"],
      "env": { "SPACEPOST_API_KEY": "sp_live_YOUR_API_KEY" }
    }
  }
}

VS Code

{
  "inputs": [
    { "id": "spacepost-key", "type": "promptString", "description": "SpacePost API key", "password": true }
  ],
  "servers": {
    "spacepost": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@spacepost/mcp"],
      "env": { "SPACEPOST_API_KEY": "${input:spacepost-key}" }
    }
  }
}

npx -y @spacepost/mcp --help listet die Optionen auf, und --list-tools gibt die Tools aus, die eine Konfiguration bereitstellt.

Optionen

Lokales Flag	Gehostete Query	Wirkung
--read-only	read_only=true	Nur Tools für GET-Endpoints (list_*, get_*, get_broadcast_readiness)
--permission sending_access	automatisch, aus deinem Schlüssel	Nur die Tools, die ein sending_access-Schlüssel nutzen kann
--toolsets emails,domains	toolsets=emails,domains	Nur Tools dieser API-Bereiche: emails, domains, apikeys, webhooks, audiences, contacts, broadcasts, suppressions, tenants (die Abschnitte der Referenz; Groß-/Kleinschreibung, Leerzeichen und Bindestriche werden ignoriert, daher funktioniert auch api-keys)

Beides lässt sich kombinieren.

Wie Tools der API entsprechen

• Ein Tool pro Endpoint, benannt nach der operationId des Endpoints in snake_case: Aus sendEmail wird send_email, aus getBroadcastReadiness wird get_broadcast_readiness, aus pauseTenant wird pause_tenant. Die API-Referenz dokumentiert jedes Feld.
• Argumente sind ein flaches Objekt: Pfadparameter (in snake_case, z. B. id, audience_id, ref), Query-Parameter (limit, after, before) und die Felder des JSON-Bodys (from, to, subject, …). Hat ein Body-Feld denselben Namen wie ein Parameter, heißt es body_<field>. Ein Body, der kein Objekt ist, etwa das Array für send_batch_emails, wird als body übergeben.
• idempotency_key bei send_email und send_batch_emails setzt den Header Idempotency-Key, sodass Wiederholungen nie doppelt senden.
• Ergebnisse sind die JSON-Antwort der API, auch als strukturierter Inhalt. Fehler kommen mit isError: true und demselben Body { "statusCode", "name", "message" } wie bei der REST-API zurück, plus einem Hinweis, was als Nächstes zu tun ist.
• Annotationen sagen dem Client, was ein Tool tut: Lesende Tools sind readOnlyHint, Löschvorgänge, cancel_email und pause_tenant sind destructiveHint, und die Tools, die E-Mails senden (send_email, send_batch_emails, send_broadcast), sind openWorldHint. Clients entscheiden damit, wann sie dich vor dem Ausführen eines Tools fragen.

Beispiel-Prompts

• “Sende eine Test-E-Mail von onboarding@test.spacepost.dev an delivered@test.spacepost.dev, die Hallo sagt.”
• “Füge die Domain acme.com hinzu und sag mir, welche DNS-Einträge ich anlegen muss.”
• “Wurde die E-Mail zugestellt, die ich gestern an ada@example.com gesendet habe?”
• “Storniere die geplante E-Mail an die Beta-Liste.”
• “Erstelle einen Webhook an https://acme.com/hooks für Bounces und Beschwerden.”
• “Entwirf eine Kampagne an meine Zielgruppe Newsletter, prüfe sie auf Zustellbarkeitsprobleme, aber sende sie noch nicht.”
• “Welche meiner Tenants sind pausiert, und warum?”

Tipp

Gib deinem Coding-Agenten auch die Doku: /llms.txt ist ein Index und /llms-full.txt enthält die wichtigsten Seiten in einer Datei.