Server MCP

SpacePost parla il Model Context Protocol, quindi gli assistenti di IA possono inviare email e gestire per tuo conto domini, chiavi API, webhook, pubblici, contatti, campagne, soppressioni e tenant.

Ogni endpoint del riferimento API è uno strumento MCP. Gli strumenti sono generati dallo stesso documento OpenAPI del riferimento, quindi quando l’API acquisisce una funzionalità, il server MCP la offre automaticamente: non c’è un elenco separato da mantenere o da attendere.

Puoi connetterti in due modi:

• In hosting (consigliato): https://api.spacepost.dev/mcp, Streamable HTTP, autenticato con la tua chiave API. Niente da installare.
• Locale: npx -y @spacepost/mcp, un server stdio che chiama l’API dalla tua macchina. Le definizioni degli strumenti sono incluse nel pacchetto, quindi si avvia anche offline.

Attenzione

L’assistente agisce con i permessi della chiave API che gli fornisci, esattamente come se chiamasse l’API REST: stessi controlli sui permessi, limiti di frequenza, quote e idempotenza. Usa una chiave dedicata. Una chiave sending_access può usare solo send_email e send_batch_emails: per una chiave del genere il server in hosting elenca solo questi due, e qualsiasi altro strumento risponde restricted_api_key. Aggiungi --read-only (in locale) o ?read_only=true (in hosting) per esporre solo gli strumenti di lettura.

Connettersi al server in hosting

Invia la tua chiave API come 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"

Usa claude mcp list per confermare.

Claude Desktop

Claude Desktop avvia server locali (stdio) da claude_desktop_config.json, quindi collega l’endpoint in hosting con 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" }
    }
  }
}

Riavvia Claude Desktop. In alternativa usa il server locale.

Cursor

Aggiungi a .cursor/mcp.json nel tuo progetto, oppure a ~/.cursor/mcp.json a livello globale:

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

VS Code

Aggiungi a .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 chiede la chiave la prima volta e la tiene fuori dal file.

Restringi l’elenco degli strumenti con parametri di query nell’URL, ad esempio https://api.spacepost.dev/mcp?read_only=true&toolsets=emails,domains.

Il server in hosting è stateless: ogni richiesta è indipendente, quindi GET e DELETE su /mcp rispondono 405 e non c’è alcuna sessione da riprendere.

Eseguire il server in locale

Variabile	Obbligatoria	Descrizione
SPACEPOST_API_KEY	Sì	La tua chiave API
SPACEPOST_BASE_URL	No	URL alternativo dell’API, predefinito https://api.spacepost.dev
SPACEPOST_DEFAULT_FROM	No	Mittente usato quando l’assistente chiama send_email senza from, ad esempio Acme <hello@acme.com>
SPACEPOST_READ_ONLY	No	true equivale a --read-only
SPACEPOST_TOOLSETS	No	Come --toolsets, ad esempio emails,domains
SPACEPOST_PERMISSION	No	Come --permission; imposta sending_access quando la chiave può solo inviare

Claude Code

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

Aggiungi -e SPACEPOST_DEFAULT_FROM="Acme <hello@acme.com>" per impostare un mittente predefinito, oppure dei flag dopo il nome del pacchetto, come 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 elenca le opzioni e --list-tools stampa gli strumenti esposti da una configurazione.

Opzioni

Flag locale	Query in hosting	Effetto
--read-only	read_only=true	Solo gli strumenti per gli endpoint GET (list_*, get_*, get_broadcast_readiness)
--permission sending_access	automatico, dalla tua chiave	Solo gli strumenti che una chiave sending_access può usare
--toolsets emails,domains	toolsets=emails,domains	Solo gli strumenti di queste aree dell’API: emails, domains, apikeys, webhooks, audiences, contacts, broadcasts, suppressions, tenants (le sezioni del riferimento; maiuscole, spazi e trattini vengono ignorati, quindi funziona anche api-keys)

Si possono combinare.

Come gli strumenti corrispondono all’API

• Uno strumento per endpoint, con il nome dell’operationId dell’endpoint in snake_case: sendEmail diventa send_email, getBroadcastReadiness diventa get_broadcast_readiness, pauseTenant diventa pause_tenant. Il riferimento API documenta ogni campo.
• Gli argomenti sono un unico oggetto piatto: parametri di percorso (in snake_case, ad es. id, audience_id, ref), parametri di query (limit, after, before) e i campi del corpo JSON (from, to, subject, …). Se un campo del corpo ha lo stesso nome di un parametro, si chiama body_<field>. Un corpo che non è un oggetto, come l’array per send_batch_emails, viene passato come body.
• idempotency_key su send_email e send_batch_emails imposta l’header Idempotency-Key, così i nuovi tentativi non inviano mai due volte.
• I risultati sono la risposta JSON dell’API, anche come contenuto strutturato. Gli errori tornano con isError: true e lo stesso corpo { "statusCode", "name", "message" } dell’API REST, più un suggerimento su cosa fare dopo.
• Le annotazioni dicono al client che cosa fa uno strumento: gli strumenti di lettura sono readOnlyHint, le eliminazioni, cancel_email e pause_tenant sono destructiveHint, e gli strumenti che inviano email (send_email, send_batch_emails, send_broadcast) sono openWorldHint. I client li usano per decidere quando chiederti conferma prima di eseguire uno strumento.

Prompt di esempio

• “Send a test email from onboarding@test.spacepost.dev to delivered@test.spacepost.dev saying hello.”
• “Add the domain acme.com and tell me which DNS records to create.”
• “Did the email I sent to ada@example.com yesterday get delivered?”
• “Cancel the scheduled email to the beta list.”
• “Create a webhook to https://acme.com/hooks for bounces and complaints.”
• “Draft a broadcast to my Newsletter audience, check it for deliverability problems, but don’t send it yet.”
• “Which of my tenants are paused, and why?”

Consiglio

Dai anche la documentazione al tuo agente di programmazione: /llms.txt è un indice e /llms-full.txt contiene le pagine chiave in un unico file.