Servidor MCP

SpacePost habla el Model Context Protocol, así que los asistentes de IA pueden enviar correo y gestionar dominios, claves de API, webhooks, audiencias, contactos, campañas, supresiones y tenants en tu nombre.

Cada endpoint de la referencia de la API es una herramienta MCP. Las herramientas se generan a partir del mismo documento OpenAPI que la referencia, así que cuando la API gana una función, el servidor MCP la ofrece automáticamente: no hay una lista aparte que mantener ni que esperar.

Puedes conectarte de dos formas:

• Alojado (recomendado): https://api.spacepost.dev/mcp, Streamable HTTP, autenticado con tu clave de API. No hay nada que instalar.
• Local: npx -y @spacepost/mcp, un servidor stdio que llama a la API desde tu máquina. Las definiciones de las herramientas vienen dentro del paquete, así que arranca sin conexión.

Precaución

El asistente actúa con los permisos de la clave de API que le des, exactamente como si llamara a la API REST: las mismas comprobaciones de permisos, límites de tasa, cuotas e idempotencia. Usa una clave dedicada. Una clave sending_access solo puede usar send_email y send_batch_emails: el servidor alojado lista solo esas dos para una clave así, y cualquier otra herramienta responde restricted_api_key. Añade --read-only (local) o ?read_only=true (alojado) para exponer solo las herramientas de lectura.

Conectarse al servidor alojado

Envía tu clave de API como token 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"

Usa claude mcp list para confirmarlo.

Claude Desktop

Claude Desktop inicia servidores locales (stdio) desde claude_desktop_config.json, así que conecta el endpoint alojado 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" }
    }
  }
}

Reinicia Claude Desktop. O usa el servidor local en su lugar.

Cursor

Añádelo a .cursor/mcp.json en tu proyecto, o a ~/.cursor/mcp.json de forma global:

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

VS Code

Añádelo 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 te pide la clave la primera vez y la mantiene fuera del archivo.

Limita la lista de herramientas con parámetros de consulta en la URL, por ejemplo https://api.spacepost.dev/mcp?read_only=true&toolsets=emails,domains.

El servidor alojado no tiene estado: cada petición es independiente, así que GET y DELETE sobre /mcp responden 405 y no hay ninguna sesión que reanudar.

Ejecutar el servidor en local

Variable	Obligatoria	Descripción
SPACEPOST_API_KEY	Sí	Tu clave de API
SPACEPOST_BASE_URL	No	URL alternativa de la API, por defecto https://api.spacepost.dev
SPACEPOST_DEFAULT_FROM	No	Remitente que se usa cuando el asistente llama a send_email sin from, por ejemplo Acme <hello@acme.com>
SPACEPOST_READ_ONLY	No	true equivale a --read-only
SPACEPOST_TOOLSETS	No	Igual que --toolsets, por ejemplo emails,domains
SPACEPOST_PERMISSION	No	Igual que --permission; define sending_access cuando la clave solo pueda enviar

Claude Code

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

Añade -e SPACEPOST_DEFAULT_FROM="Acme <hello@acme.com>" para definir un remitente por defecto, o flags después del nombre del paquete, como 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 lista las opciones, y --list-tools muestra las herramientas que expone una configuración.

Opciones

Flag local	Consulta alojada	Efecto
--read-only	read_only=true	Solo herramientas para endpoints GET (list_*, get_*, get_broadcast_readiness)
--permission sending_access	automático, según tu clave	Solo las herramientas que puede usar una clave sending_access
--toolsets emails,domains	toolsets=emails,domains	Solo herramientas de estas áreas de la API: emails, domains, apikeys, webhooks, audiences, contacts, broadcasts, suppressions, tenants (las secciones de la referencia; se ignoran mayúsculas, espacios y guiones, así que api-keys también funciona)

Se pueden combinar.

Cómo se corresponden las herramientas con la API

• Una herramienta por endpoint, con el nombre del operationId del endpoint en snake_case: sendEmail pasa a ser send_email, getBroadcastReadiness pasa a ser get_broadcast_readiness, pauseTenant pasa a ser pause_tenant. La referencia de la API documenta cada campo.
• Los argumentos son un único objeto plano: parámetros de ruta (en snake_case, p. ej. id, audience_id, ref), parámetros de consulta (limit, after, before) y los campos del cuerpo JSON (from, to, subject, …). Si un campo del cuerpo se llama igual que un parámetro, se llama body_<field>. Un cuerpo que no es un objeto, como el array de send_batch_emails, se pasa como body.
• idempotency_key en send_email y send_batch_emails define el encabezado Idempotency-Key, así que los reintentos nunca envían dos veces.
• Los resultados son la respuesta JSON de la API, también como contenido estructurado. Los errores llegan con isError: true y el mismo cuerpo { "statusCode", "name", "message" } que la API REST, más una pista sobre qué hacer a continuación.
• Las anotaciones le dicen al cliente qué hace una herramienta: las de lectura son readOnlyHint, las de borrado, cancel_email y pause_tenant son destructiveHint, y las que envían correo (send_email, send_batch_emails, send_broadcast) son openWorldHint. Los clientes las usan para decidir cuándo preguntarte antes de ejecutar una herramienta.

Ejemplos de prompts

• “Envía un correo de prueba desde onboarding@test.spacepost.dev a delivered@test.spacepost.dev diciendo hola.”
• “Añade el dominio acme.com y dime qué registros DNS debo crear.”
• “¿Se entregó el correo que le envié ayer a ada@example.com?”
• “Cancela el correo programado para la lista beta.”
• “Crea un webhook a https://acme.com/hooks para rebotes y quejas.”
• “Prepara un borrador de campaña para mi audiencia Newsletter, revisa si tiene problemas de entregabilidad, pero no la envíes todavía.”
• “¿Cuáles de mis tenants están pausados y por qué?”

Consejo

Dale también la documentación a tu agente de programación: /llms.txt es un índice y /llms-full.txt reúne las páginas clave en un solo archivo.