Serveur MCP

SpacePost parle le Model Context Protocol : les assistants IA peuvent envoyer des e-mails et gérer en votre nom les domaines, clés API, webhooks, audiences, contacts, campagnes, suppressions et tenants.

Chaque endpoint de la référence de l’API est un outil MCP. Les outils sont générés à partir du même document OpenAPI que la référence : quand l’API gagne une fonctionnalité, le serveur MCP la propose automatiquement. Il n’y a pas de liste séparée à maintenir ni à attendre.

Vous pouvez vous connecter de deux façons :

• Hébergé (recommandé) : https://api.spacepost.dev/mcp, en Streamable HTTP, authentifié avec votre clé API. Rien à installer.
• Local : npx -y @spacepost/mcp, un serveur stdio qui appelle l’API depuis votre machine. Les définitions des outils sont incluses dans le paquet, il démarre donc hors ligne.

Attention

L’assistant agit avec les permissions de la clé API que vous lui donnez, exactement comme s’il appelait l’API REST : mêmes contrôles de permissions, limites de débit, quotas et idempotence. Utilisez une clé dédiée. Une clé sending_access ne peut utiliser que send_email et send_batch_emails : pour une telle clé, le serveur hébergé ne liste que ces deux outils, et tout autre outil répond restricted_api_key. Ajoutez --read-only (local) ou ?read_only=true (hébergé) pour n’exposer que les outils de lecture.

Se connecter au serveur hébergé

Envoyez votre clé API comme jeton bearer : 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"

Utilisez claude mcp list pour confirmer.

Claude Desktop

Claude Desktop lance des serveurs locaux (stdio) depuis claude_desktop_config.json : reliez donc l’endpoint hébergé avec mcp-remote (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" }
    }
  }
}

Redémarrez Claude Desktop. Vous pouvez aussi utiliser le serveur local à la place.

Cursor

Ajoutez à .cursor/mcp.json dans votre projet, ou à ~/.cursor/mcp.json globalement :

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

VS Code

Ajoutez à .vscode/mcp.json :

{
  "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 demande la clé la première fois et la garde hors du fichier.

Restreignez la liste des outils avec des paramètres de requête dans l’URL, par exemple https://api.spacepost.dev/mcp?read_only=true&toolsets=emails,domains.

Le serveur hébergé est sans état : chaque requête est indépendante, donc GET et DELETE sur /mcp répondent 405 et il n’y a pas de session à reprendre.

Exécuter le serveur en local

Variable	Requise	Description
SPACEPOST_API_KEY	Oui	Votre clé API
SPACEPOST_BASE_URL	Non	URL d’API alternative, https://api.spacepost.dev par défaut
SPACEPOST_DEFAULT_FROM	Non	Expéditeur utilisé lorsque l’assistant appelle send_email sans from, par exemple Acme <hello@acme.com>
SPACEPOST_READ_ONLY	Non	true équivaut à --read-only
SPACEPOST_TOOLSETS	Non	Équivaut à --toolsets, par exemple emails,domains
SPACEPOST_PERMISSION	Non	Équivaut à --permission ; indiquez sending_access lorsque la clé ne sert qu’à envoyer

Claude Code

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

Ajoutez -e SPACEPOST_DEFAULT_FROM="Acme <hello@acme.com>" pour définir un expéditeur par défaut, ou des options après le nom du paquet, comme 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 liste les options, et --list-tools affiche les outils qu’une configuration expose.

Options

Option locale	Paramètre hébergé	Effet
--read-only	read_only=true	Uniquement les outils des endpoints GET (list_*, get_*, get_broadcast_readiness)
--permission sending_access	automatique, d’après votre clé	Uniquement les outils qu’une clé sending_access peut utiliser
--toolsets emails,domains	toolsets=emails,domains	Uniquement les outils de ces domaines de l’API : emails, domains, apikeys, webhooks, audiences, contacts, broadcasts, suppressions, tenants (les sections de la référence ; la casse, les espaces et les tirets sont ignorés, donc api-keys fonctionne aussi)

Les deux peuvent être combinés.

Correspondance entre les outils et l’API

• Un outil par endpoint, nommé d’après l’operationId de l’endpoint en snake_case : sendEmail devient send_email, getBroadcastReadiness devient get_broadcast_readiness, pauseTenant devient pause_tenant. La référence de l’API documente chaque champ.
• Les arguments forment un seul objet plat : paramètres de chemin (en snake_case, par ex. id, audience_id, ref), paramètres de requête (limit, after, before) et champs du corps JSON (from, to, subject, …). Si un champ du corps porte le même nom qu’un paramètre, il s’appelle body_<field>. Un corps qui n’est pas un objet, comme le tableau de send_batch_emails, est passé dans body.
• idempotency_key sur send_email et send_batch_emails définit l’en-tête Idempotency-Key : les nouvelles tentatives n’envoient donc jamais deux fois.
• Les résultats sont la réponse JSON de l’API, également fournie en contenu structuré. Les erreurs reviennent avec isError: true et le même corps { "statusCode", "name", "message" } que l’API REST, plus une indication sur la marche à suivre.
• Les annotations indiquent au client ce que fait un outil : les outils de lecture sont readOnlyHint, les suppressions, cancel_email et pause_tenant sont destructiveHint, et les outils qui envoient des e-mails (send_email, send_batch_emails, send_broadcast) sont openWorldHint. Les clients s’en servent pour décider quand vous demander confirmation avant d’exécuter un outil.

Exemples de prompts

• « Envoie un e-mail de test de onboarding@test.spacepost.dev à delivered@test.spacepost.dev pour dire bonjour. »
• « Ajoute le domaine acme.com et dis-moi quels enregistrements DNS créer. »
• « L’e-mail que j’ai envoyé hier à ada@example.com a-t-il été distribué ? »
• « Annule l’e-mail planifié pour la liste bêta. »
• « Crée un webhook vers https://acme.com/hooks pour les rebonds et les plaintes. »
• « Prépare un brouillon de campagne pour mon audience Newsletter, vérifie s’il pose des problèmes de délivrabilité, mais ne l’envoie pas encore. »
• « Lesquels de mes tenants sont en pause, et pourquoi ? »

Astuce

Donnez aussi la documentation à votre agent de code : /llms.txt est un index et /llms-full.txt contient les pages clés dans un seul fichier (ces fichiers sont en anglais).