MCP 服务器

SpacePost 支持 Model Context Protocol，因此 AI 助手可以代你发送邮件，并管理域名、API 密钥、Webhook、受众、联系人、群发、抑制列表和租户。

API 参考中的每个端点都是一个 MCP 工具。 这些工具与 API 参考由同一份 OpenAPI 文档生成，因此 API 新增功能时，MCP 服务器会自动提供：没有需要单独维护或等待更新的工具列表。

有两种连接方式：

托管（推荐）：https://api.spacepost.dev/mcp，Streamable HTTP，使用你的 API 密钥进行身份验证。无需安装任何东西。
本地：npx -y @spacepost/mcp，一个从你的机器调用 API 的 stdio 服务器。工具定义随包一起发布，因此可以离线启动。

连接托管服务器

以 Bearer 令牌的形式发送你的 API 密钥：Authorization: Bearer sp_live_...。

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

使用 claude mcp list 确认。

Claude Desktop 从 claude_desktop_config.json 启动本地（stdio）服务器，因此请用 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" }
    }
  }
}

重启 Claude Desktop。也可以改用本地服务器。

添加到项目中的 .cursor/mcp.json，或全局的 ~/.cursor/mcp.json：

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

添加到 .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 会在首次使用时询问密钥，并且不会把它写入文件。

可以通过 URL 上的查询参数缩小工具列表，例如 https://api.spacepost.dev/mcp?read_only=true&toolsets=emails,domains。

托管服务器是无状态的：每个请求都相互独立，因此对 /mcp 的 GET 和 DELETE 请求会返回 405，也没有可恢复的会话。

在本地运行服务器

变量	是否必需	说明
`SPACEPOST_API_KEY`	是	你的 API 密钥
`SPACEPOST_BASE_URL`	否	备用的 API URL，默认为 `https://api.spacepost.dev`
`SPACEPOST_DEFAULT_FROM`	否	助手调用 `send_email` 但未提供 `from` 时使用的发件人，例如 `Acme <hello@acme.com>`
`SPACEPOST_READ_ONLY`	否	`true` 等同于 `--read-only`
`SPACEPOST_TOOLSETS`	否	等同于 `--toolsets`，例如 `emails,domains`
`SPACEPOST_PERMISSION`	否	等同于 `--permission`；密钥只能发信时请设置为 `sending_access`

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

添加 -e SPACEPOST_DEFAULT_FROM="Acme <hello@acme.com>" 可设置默认发件人，也可以在包名之后添加参数，例如 npx -y @spacepost/mcp --read-only。

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

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

{
  "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 会列出所有选项，--list-tools 会打印当前配置提供的工具。

选项

本地参数	托管查询参数	作用
`--read-only`	`read_only=true`	只提供 `GET` 端点的工具（`list_`、`get_`、`get_broadcast_readiness`）
`--permission sending_access`	自动，根据你的密钥	只提供 `sending_access` 密钥可以使用的工具
`--toolsets emails,domains`	`toolsets=emails,domains`	只提供这些 API 领域的工具：`emails`、`domains`、`apikeys`、`webhooks`、`audiences`、`contacts`、`broadcasts`、`suppressions`、`tenants`（即 API 参考的各个章节；忽略大小写、空格和连字符，因此 `api-keys` 也可以）

两者可以组合使用。

工具与 API 的对应关系

每个端点一个工具，以端点的 operationId 的 snake_case 形式命名：sendEmail 变为 send_email，getBroadcastReadiness 变为 get_broadcast_readiness，pauseTenant 变为 pause_tenant。API 参考记录了每个字段。
参数是一个扁平对象：路径参数（snake_case，例如 id、audience_id、ref）、查询参数（limit、after、before）以及 JSON 请求体的字段（from、to、subject 等）。如果某个请求体字段与参数同名，则称为 body_<field>。不是对象的请求体（例如 send_batch_emails 的数组）通过 body 传入。
send_email 和 send_batch_emails 上的 idempotency_key 会设置 Idempotency-Key 标头，因此重试永远不会重复发送。
结果是 API 的 JSON 响应，同时也以结构化内容返回。出错时会返回 isError: true，以及与 REST API 相同的 { "statusCode", "name", "message" } 响应体，外加下一步该怎么做的提示。
标注告诉客户端工具的作用：读取类工具为 readOnlyHint，删除操作、cancel_email 和 pause_tenant 为 destructiveHint，发送邮件的工具（send_email、send_batch_emails、send_broadcast）为 openWorldHint。客户端据此决定何时在运行工具前征求你的确认。

提示词示例

“从 onboarding@test.spacepost.dev 向 delivered@test.spacepost.dev 发送一封打招呼的测试邮件。”
“添加域名 acme.com，并告诉我需要创建哪些 DNS 记录。”
“我昨天发给 ada@example.com 的邮件送达了吗？”
“取消发给 beta 名单的定时邮件。”
“创建一个 Webhook，把退信和投诉发送到 https://acme.com/hooks。”
“为我的 Newsletter 受众起草一封群发，检查它有没有送达率问题，但先不要发送。”
“我的哪些租户被暂停了，原因是什么？”