@spacepost/mcp

An MCP server that gives AI assistants the whole SpacePost API: one tool per endpoint of the API reference, generated from the OpenAPI document. New API features become MCP tools automatically. Docs: https://docs.spacepost.dev/tools/mcp/

SpacePost is a Resend-compatible transactional email API on Amazon SES (EU company), with an SMTP relay and this MCP server.

Two ways to use it:

• Hosted: https://api.spacepost.dev/mcp (Streamable HTTP) with Authorization: Bearer sp_live_.... Nothing to install.

• Local (this package): npx -y @spacepost/mcp, stdio. The spec is bundled, so it starts offline.

Create an API key in the SpacePost dashboard. In the official MCP Registry the server is dev.spacepost/mcp; on npm it is @spacepost/mcp.

Configuration

The hosted endpoint takes the same options as query parameters: /mcp?read_only=true&toolsets=emails,domains. It derives the permission filter from the caller's key: sending_access keys see only the sending tools in tools/list. Other tools are not blocked by MCP; calling one goes to the API, which answers restricted_api_key as it does for REST.

Claude Code

# hosted
claude mcp add --transport http spacepost https://api.spacepost.dev/mcp --header "Authorization: Bearer sp_live_..."
# local
claude mcp add spacepost -e SPACEPOST_API_KEY=sp_live_... -e SPACEPOST_DEFAULT_FROM="Acme <hi@acme.com>" -- npx -y @spacepost/mcp

Cursor (~/.cursor/mcp.json or .cursor/mcp.json)

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

Claude Desktop (claude_desktop_config.json)

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

Related MCP server: Resend MCP Server

How tools are built

• Name: operationId in snake_case (sendEmail → send_email, getBroadcastReadiness → get_broadcast_readiness). The 12 hand-written tools of 0.1 keep their names.

• Input: one flat JSON Schema object with path params (snake_case: audience_id, id_or_email), query params, header params (Idempotency-Key → idempotency_key) and the top-level JSON body fields. A body field that collides with a parameter name is exposed as body_<field>; a non-object body (the batch array) as body. $ref/allOf are inlined; enums, formats, patterns, bounds, defaults and descriptions are kept.

• Description: summary + description from the spec, curated extras, the key permission and the HTTP route.

• Annotations: GET → readOnlyHint; DELETE → destructiveHint; GET/PUT/DELETE → idempotentHint; overridable per operation.

• Result: the API's JSON (text + structuredContent). Errors: isError: true with the Resend-style { statusCode, name, message } body and a hint.

Tuning a tool

Tools follow the API's OpenAPI document. Operations carry these extensions (set by SpacePost in the spec):

x-mcp: { hidden: false, description: "Extra guidance for agents.", destructive: true, idempotent: true, openWorld: true }
x-permission: sending_access # only on operations a sending_access key may call

src/overlay.ts (keyed by operationId) holds the few curated descriptions that are about using a tool well rather than the API itself; x-mcp wins when both set a field.

Development

bun install
bun run build     # dist/index.js, spec included
bun test
bun run generate  # refresh src/generated/openapi.json from https://api.spacepost.dev/openapi.json

Issues and pull requests are welcome. Security reports: security@spacepost.dev.

0.2 breaking changes: results are the raw API JSON instead of short text summaries, and verify_domain returns the verify response (call get_domain for the new status).

License

MIT, see LICENSE. © Studio 404 d.o.o.