Servidor MCP

O SpacePost fala o Model Context Protocol, então assistentes de IA podem enviar e-mails e gerenciar domínios, chaves de API, webhooks, públicos, contatos, campanhas, supressões e tenants em seu nome.

Cada endpoint da referência da API é uma ferramenta MCP. As ferramentas são geradas a partir do mesmo documento OpenAPI da referência, então, quando a API ganha um recurso, o servidor MCP o oferece automaticamente: não há uma lista separada para manter ou esperar.

Você pode se conectar de duas formas:

• Hospedado (recomendado): https://api.spacepost.dev/mcp, Streamable HTTP, autenticado com a sua chave de API. Nada para instalar.
• Local: npx -y @spacepost/mcp, um servidor stdio que chama a API a partir da sua máquina. As definições das ferramentas vêm dentro do pacote, então ele inicia offline.

Cuidado

O assistente age com as permissões da chave de API que você der a ele, exatamente como se chamasse a API REST: as mesmas verificações de permissão, limites de taxa, cotas e idempotência. Use uma chave dedicada. Uma chave sending_access só pode usar send_email e send_batch_emails: o servidor hospedado lista apenas essas duas para essa chave, e qualquer outra ferramenta responde restricted_api_key. Adicione --read-only (local) ou ?read_only=true (hospedado) para expor apenas as ferramentas de leitura.

Conectar ao servidor hospedado

Envie a sua chave de API como 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"

Use claude mcp list para confirmar.

Claude Desktop

O Claude Desktop inicia servidores locais (stdio) a partir do claude_desktop_config.json, então conecte o endpoint hospedado com 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" }
    }
  }
}

Reinicie o Claude Desktop. Ou use o servidor local.

Cursor

Adicione ao .cursor/mcp.json do seu projeto, ou ao ~/.cursor/mcp.json para valer globalmente:

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

VS Code

Adicione ao .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}" }
    }
  }
}

O VS Code pede a chave na primeira vez e a mantém fora do arquivo.

Restrinja a lista de ferramentas com parâmetros de consulta na URL, por exemplo https://api.spacepost.dev/mcp?read_only=true&toolsets=emails,domains.

O servidor hospedado não tem estado: cada requisição é independente, então GET e DELETE em /mcp respondem 405 e não há sessão para retomar.

Executar o servidor localmente

Variável	Obrigatória	Descrição
SPACEPOST_API_KEY	Sim	Sua chave de API
SPACEPOST_BASE_URL	Não	URL alternativa da API; o padrão é https://api.spacepost.dev
SPACEPOST_DEFAULT_FROM	Não	Remetente usado quando o assistente chama send_email sem from, por exemplo Acme <hello@acme.com>
SPACEPOST_READ_ONLY	Não	true equivale a --read-only
SPACEPOST_TOOLSETS	Não	O mesmo que --toolsets, por exemplo emails,domains
SPACEPOST_PERMISSION	Não	O mesmo que --permission; defina sending_access quando a chave só puder enviar

Claude Code

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

Adicione -e SPACEPOST_DEFAULT_FROM="Acme <hello@acme.com>" para definir um remetente padrão, ou flags depois do nome do pacote, 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 as opções, e --list-tools mostra as ferramentas que uma configuração expõe.

Opções

Flag local	Parâmetro hospedado	Efeito
--read-only	read_only=true	Apenas as ferramentas dos endpoints GET (list_*, get_*, get_broadcast_readiness)
--permission sending_access	automático, a partir da sua chave	Apenas as ferramentas que uma chave sending_access pode usar
--toolsets emails,domains	toolsets=emails,domains	Apenas as ferramentas destas áreas da API: emails, domains, apikeys, webhooks, audiences, contacts, broadcasts, suppressions, tenants (as seções da referência; maiúsculas, espaços e hífens são ignorados, então api-keys também funciona)

As opções podem ser combinadas.

Como as ferramentas correspondem à API

• Uma ferramenta por endpoint, com o nome do operationId do endpoint em snake_case: sendEmail vira send_email, getBroadcastReadiness vira get_broadcast_readiness, pauseTenant vira pause_tenant. A referência da API documenta todos os campos.
• Os argumentos são um único objeto plano: parâmetros de caminho (em snake_case, por exemplo id, audience_id, ref), parâmetros de consulta (limit, after, before) e os campos do corpo JSON (from, to, subject, …). Se um campo do corpo tiver o mesmo nome de um parâmetro, ele se chama body_<field>. Um corpo que não é um objeto, como o array de send_batch_emails, é passado como body.
• idempotency_key em send_email e send_batch_emails define o cabeçalho Idempotency-Key, então novas tentativas nunca enviam duas vezes.
• Os resultados são a resposta JSON da API, também como conteúdo estruturado. Os erros voltam com isError: true e o mesmo corpo { "statusCode", "name", "message" } da API REST, além de uma dica sobre o que fazer em seguida.
• As anotações dizem ao cliente o que uma ferramenta faz: as ferramentas de leitura são readOnlyHint, as exclusões, cancel_email e pause_tenant são destructiveHint, e as ferramentas que enviam e-mails (send_email, send_batch_emails, send_broadcast) são openWorldHint. Os clientes as usam para decidir quando perguntar a você antes de executar uma ferramenta.

Exemplos de prompts

• “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?”

Dica

Dê a documentação também ao seu agente de código: /llms.txt é um índice e /llms-full.txt reúne as páginas principais em um único arquivo.