MCP 서버

SpacePost는 Model Context Protocol을 지원하므로 AI 어시스턴트가 사용자를 대신해 이메일을 보내고 도메인, API 키, 웹훅, 오디언스, 연락처, 브로드캐스트, 발송 제외 항목, 테넌트를 관리할 수 있습니다.

API 레퍼런스의 모든 엔드포인트가 MCP 도구입니다. 도구는 레퍼런스와 같은 OpenAPI 문서에서 생성되므로, API에 기능이 추가되면 MCP 서버도 자동으로 제공합니다. 따로 관리하거나 기다려야 하는 목록이 없습니다.

두 가지 방법으로 연결할 수 있습니다.

• 호스팅(권장): https://api.spacepost.dev/mcp, Streamable HTTP, API 키로 인증합니다. 설치할 것이 없습니다.
• 로컬: npx -y @spacepost/mcp, 내 컴퓨터에서 API를 호출하는 stdio 서버입니다. 도구 정의가 패키지에 포함되어 있어 오프라인에서도 시작됩니다.

주의

어시스턴트는 제공한 API 키의 권한으로, REST API를 직접 호출할 때와 똑같이 동작합니다. 권한 검사, 요청 한도, 할당량, 멱등성도 같습니다. 전용 키를 사용하세요. sending_access 키는 send_email과 send_batch_emails만 사용할 수 있습니다. 이런 키에는 호스팅 서버가 이 두 도구만 나열하며, 다른 도구는 restricted_api_key로 응답합니다. 읽기 도구만 노출하려면 --read-only(로컬) 또는 ?read_only=true(호스팅)를 추가하세요.

호스팅 서버에 연결하기

API 키를 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"

claude mcp list로 확인합니다.

Claude Desktop

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

프로젝트의 .cursor/mcp.json에, 전역으로 쓰려면 ~/.cursor/mcp.json에 추가하세요.

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

VS Code

.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	아니요	어시스턴트가 from 없이 send_email을 호출할 때 사용하는 발신자, 예: Acme <hello@acme.com>
SPACEPOST_READ_ONLY	아니요	true는 --read-only와 같습니다
SPACEPOST_TOOLSETS	아니요	--toolsets와 같습니다, 예: emails,domains
SPACEPOST_PERMISSION	아니요	--permission과 같습니다. 키가 발송 전용이면 sending_access로 설정하세요

Claude Code

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.

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는 옵션을 나열하고, --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-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으로 보낸 이메일이 전달됐어?”
• “베타 목록으로 예약된 이메일을 취소해 줘.”
• “반송과 스팸 신고에 대해 https://acme.com/hooks로 가는 웹훅을 만들어 줘.”
• “내 Newsletter 오디언스에 보낼 브로드캐스트 초안을 만들고 전달률 문제가 있는지 확인해 줘. 아직 보내지는 마.”
• “내 테넌트 중 일시 중지된 건 어떤 것이고 이유는 뭐야?”

팁

코딩 에이전트에도 문서를 알려 주세요. /llms.txt는 색인이고 /llms-full.txt에는 핵심 페이지가 한 파일에 담겨 있습니다.