AI 에이전트로 샌드고 연동 끝내기 — MCP 서버와 계정 API

샌드고 연동에서 코드는 마지막 한 단계고, 그 앞에는 계정 설정이 있습니다. 조직을 고르고, 키를 받고, 발신번호와 템플릿을 등록하는 일 — 지금까지는 이 전부가 브라우저에서 클릭해야 하는 작업이었습니다.

이제는 아닙니다. 충전을 제외한 모든 작업이 API 이고, 코딩 에이전트가 직접 호출할 수 있습니다.

딱 한 번만 사람이 합니다: 콘솔에서 에이전트 토큰을 발급해 환경변수로 넘기는 것. 애플리케이션 키는 자기 자신을 만들 수 없으므로 이 단계는 없앨 수 없습니다.

1단계 — 에이전트 토큰 발급 (유일한 수동 단계)

샌드고 콘솔에 로그인해 연동 관리 → AI 에이전트 토큰으로 갑니다. 이름과 권한 범위를 고르면 토큰이 한 번 표시됩니다.

권한 범위는 여섯 개입니다.

범위	할 수 있는 일
account:read	조직, 키 목록, 발신번호, 템플릿, 잔액 조회
keys:write	애플리케이션 키 발급·폐기, 허용 IP 관리
senders:write	문자 발신번호 등록, 카카오 채널 연동
templates:write	알림톡·브랜드메시지·문자 템플릿 등록, 검수 요청
ops:write	웹훅 구독, 짧은 URL, 이미지 업로드
messages:send	실제 발송 (크레딧 차감)

기본값은 messages:send 를 뺀 나머지 전부입니다. 셋업은 에이전트에게 맡기고 발송은 사람이 한 번 더 확인하는 구성이 가장 흔하기 때문입니다.

받은 값을 환경변수에 둡니다. 저장소에 커밋하지 마세요.

export SENDGO_AGENT_TOKEN="여기에-발급받은-토큰"

2단계 — MCP 서버 등록

MCP(Model Context Protocol)를 지원하는 에이전트라면 주소 하나만 등록하면 끝입니다.

Claude Code:

claude mcp add --transport http sendgo https://sendgo.io/mcp \
  --header "Authorization: Bearer $SENDGO_AGENT_TOKEN"

Cursor · Windsurf · 그 밖의 MCP 클라이언트는 설정 파일에 같은 내용을 씁니다.

{
  "mcpServers": {
    "sendgo": {
      "type": "http",
      "url": "https://sendgo.io/mcp",
      "headers": {
        "Authorization": "Bearer ${SENDGO_AGENT_TOKEN}"
      }
    }
  }
}

등록하면 두 가지가 함께 들어옵니다.

• 도구 — 공개 API 의 모든 엔드포인트. 도구 목록은 openapi.yaml 에서 생성되므로 스펙과 어긋날 수 없습니다. 토큰에 없는 범위의 도구는 목록에 나타나지 않습니다.
• 리소스 — SDK 가이드 20종과 이 쿡북 전체, 그리고 에이전트 규칙 파일(sendgo://rules). 에이전트가 언어별 관용구를 웹에서 찾지 않고 여기서 읽습니다.

MCP 를 쓰지 않는다면 3단계의 REST 호출을 그대로 쓰면 됩니다.

3단계 — 조직 선택과 키 발급

에이전트에게 시킬 첫 호출은 현재 상태 확인입니다.

curl -s https://sendgo.io/api/v2/account \
  -H "Authorization: Bearer $SENDGO_AGENT_TOKEN"

MCP 에서는 get_account 도구입니다. 응답의 nextSteps 에 지금 막혀 있는 것이 문장으로 들어 있습니다 — 기업 승인 대기, 키 승인 대기, 토큰 범위 부족처럼 코드로 풀 수 없는 이유들입니다. 에이전트는 이 문장을 사용자에게 그대로 전달하면 됩니다.

조직 목록을 읽고 고릅니다.

curl -s https://sendgo.io/api/v2/account/organizations \
  -H "Authorization: Bearer $SENDGO_AGENT_TOKEN"

curl -s -X POST https://sendgo.io/api/v2/account/organizations/select \
  -H "Authorization: Bearer $SENDGO_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"organizationId":"조직-uuid"}'

카카오는 기업 조직만 됩니다. 알림톡·브랜드메시지는 승인된 기업 소유 애플리케이션만 쓸 수 있습니다. 개인 계정으로는 문자만 보낼 수 있으므로, 조직 목록의 kakaoAvailable 을 먼저 확인하세요.

키를 발급합니다.

curl -s -X POST https://sendgo.io/api/v2/account/api-keys \
  -H "Authorization: Bearer $SENDGO_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"production"}'

secretKey 전문은 이 응답에서 한 번만 나옵니다. 에이전트는 즉시 .env 에 써야 합니다.

SENDGO_ACCESS_KEY=...
SENDGO_SECRET_KEY=...

사이트 설정에 따라 발급 직후 상태가 PENDING 일 수 있습니다. 그 경우 운영자 승인 전까지 토큰 발급이 거부됩니다 — 발급 성공이 사용 가능을 뜻하지 않습니다.

허용 IP 를 걸 거라면 함정이 하나 있습니다.

curl -s -X POST https://sendgo.io/api/v2/account/api-keys/{apiKeyId}/allowed-ips \
  -H "Authorization: Bearer $SENDGO_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ip":"203.0.113.7","description":"production egress"}'

첫 IP 를 등록하는 순간 IP 제한이 켜집니다. 그 전까지는 제한이 없었고, 등록 후에는 목록에 없는 모든 IP 가 IP_NOT_ALLOWED 로 막힙니다. 개발 노트북에서 잘 되던 호출이 배포 후 죽는 사고가 대부분 여기서 나옵니다. 조회 응답의 callerIp 에 지금 호출한 IP 가 들어 있으니 참고하세요.

4단계 — 발신번호와 템플릿 등록

발신번호는 법령상 사전등록이 필요합니다. 등록 유형과 필요한 서류를 먼저 조회합니다.

curl -s https://sendgo.io/api/v2/senders/number-types \
  -H "Authorization: Bearer $ACCESS_TOKEN"

이후 POST /api/v2/senders 로 접수합니다. 자세한 절차는 발신번호 등록하기에 있습니다.

알림톡 템플릿은 POST /api/v2/notice-templates 로 등록하고 POST /api/v2/notice-templates/{templateCode}/inspection 으로 검수를 요청합니다. 등록·수정·검수 취소까지 전부 API 입니다 — 관리 작업을 API 로 옮기기에서 다룹니다.

등록은 접수이고, 승인이 아닙니다. 발신번호는 샌드고 운영자가, 템플릿은 카카오가 심사합니다. 에이전트가 등록 직후 발송을 이어 붙이고 "완료" 라고 보고하면 틀린 보고입니다. 웹훅을 구독해 결과를 받으세요.

curl -s -X PUT https://sendgo.io/api/v2/webhook \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/sendgo","enabled":true}'

5단계 — 발송

승인이 끝나면 발송입니다. 에이전트가 코드를 쓰기 전에 자기 언어의 SDK 가이드를 읽게 하세요 — 이름 규칙이 언어마다 달라서(templateCode vs template_code) 추측하면 컴파일되지 않는 코드가 나옵니다. MCP 에서는 sendgo://sdk/laravel 처럼 리소스로 읽고, 아니면 https://sendgo.io/ko/sdk/laravel.md 를 가져오면 됩니다.

발송 자체는 알림톡 보내기와 문자 보내기에 있는 코드와 같습니다.

에이전트에게 규칙 파일을 주기

MCP 없이도 에이전트가 올바른 코드를 쓰게 하려면, 규칙 파일을 저장소에 넣어 두는 방법이 있습니다.

curl -o AGENTS.md https://sendgo.io/sendgo-rules.md

Claude Code 는 CLAUDE.md, Cursor 는 .cursor/rules/sendgo.mdc, Copilot 은 .github/copilot-instructions.md 를 읽습니다. 파일은 카탈로그에서 생성되므로 항상 현재 상태와 일치합니다. 에이전트 연동 안내에 도구별 경로가 정리되어 있습니다.

안 되는 것

작업	가능 여부
조직 조회·전환	API · MCP
애플리케이션 키 발급·폐기·IP 관리	API · MCP
발신번호 등록·심사 접수	API · MCP
카카오 채널 연동·인증번호 요청	API · MCP
템플릿 등록·수정·검수 요청	API · MCP
발송, 결과 조회, 잔액 조회	API · MCP
웹훅 구독, 짧은 URL	API · MCP
크레딧 충전 (결제)	콘솔에서만
이미지 파일 업로드	API (multipart) — MCP 도구로는 제공하지 않습니다

카카오 채널 인증번호는 카카오가 채널 관리자 휴대폰으로 보내는 SMS 입니다. API 로 요청은 할 수 있지만 그 번호를 읽어 입력하는 것은 사람이어야 합니다 — 카카오가 직접 하는 확인이라 없앨 수 없습니다.