SubXDocs

MCP 연동

SubX MCP 서버를 연결하면 Claude, Cursor 같은 AI 도구에서 대화만으로 구독 관리 작업을 수행할 수 있습니다. 상품 등록, 오퍼링 구성, 고객 조회까지 — 대시보드를 열지 않아도 됩니다.

MCP란? Model Context Protocol의 약자로, AI 도구가 외부 서비스의 기능을 직접 호출할 수 있게 해주는 표준입니다. SubX MCP는 81개 도구를 제공하며, SubX API 전체를 커버합니다.

준비물

  • SubX 계정 (이메일 + 비밀번호)
  • API 키 — 대시보드 API 키 메뉴에서 발급
  • Node.js 20 이상

Claude Code에서 사용하기

~/.claude/settings.local.json 파일에 다음을 추가하세요:

settings.local.json
{
  "mcpServers": {
    "subx-mcp": {
      "command": "npx",
      "args": ["-y", "subx-mcp"],
      "env": {
        "SUBX_API_KEY": "your_api_key",
        "SUBX_EMAIL": "your@email.com",
        "SUBX_PASSWORD": "your-password"
      }
    }
  }
}

설정 후 Claude Code를 재시작하면 SubX 도구를 바로 사용할 수 있습니다.

Cursor에서 사용하기

프로젝트 루트에 .cursor/mcp.json 파일을 만드세요:

.cursor/mcp.json
{
  "mcpServers": {
    "subx-mcp": {
      "command": "npx",
      "args": ["-y", "subx-mcp"],
      "env": {
        "SUBX_API_KEY": "your_api_key",
        "SUBX_EMAIL": "your@email.com",
        "SUBX_PASSWORD": "your-password"
      }
    }
  }
}

환경 변수

변수필수설명
SUBX_EMAIL대시보드 모드로그인 이메일
SUBX_PASSWORD대시보드 모드로그인 비밀번호
SUBX_API_KEYSDK 모드API 키 (구독자 조회, 오퍼링 등)
SUBX_BASE_URL선택기본값 https://api.subx.dev — 커스텀 서버 사용 시에만 변경

인증 모드

  • 대시보드 모드 (이메일+비밀번호): 프로젝트, 앱, 상품, 권한, 오퍼링 등 전체 관리 도구를 사용할 수 있습니다.
  • SDK 모드 (API 키): 구독자 조회, 오퍼링 조회, 영수증 제출 등 구독자 대상 도구를 사용할 수 있습니다.
  • 두 모드를 동시에 설정하면 81개 도구 전체를 사용할 수 있습니다.

사용 예시

MCP 연결 후 AI에게 이렇게 말하면 됩니다:

"SubX에 새 프로젝트 만들고, iOS 앱 등록해줘. 번들 ID는 com.myapp.ios야"

"월간 9,900원, 연간 79,000원 상품 만들고 pro 엔타이틀먼트에 연결해줘"

"이번 달 MRR이랑 활성 구독 수 알려줘"

"user_12345 고객의 구독 상태 확인해줘"

전체 설정 워크플로우

MCP 도구만으로 처음부터 끝까지 구독 시스템을 구축하는 흐름입니다:

1. login                           → 인증
2. create_project                  → "내 앱" 프로젝트 생성
3. create_app                      → iOS 앱 등록 (com.myapp.ios)
4. create_product                  → 월간 구독 상품 생성
5. create_price                    → ₩9,900 가격 설정
6. create_entitlement              → "pro" 권한 생성
7. attach_products_to_entitlement  → 상품 → 권한 연결
8. create_offering                 → "default" 오퍼링 (현재로 설정)
9. create_package                  → "월간 플랜" 패키지
10. attach_products_to_package     → 상품 → 패키지 연결
11. create_api_key                 → SDK/서버용 API 키 생성
12. create_webhook                 → 이벤트 알림 설정

제공 도구 (81개)

카테고리도구 수주요 기능
인증2로그인, 사용자 정보
프로젝트6CRUD + 설정 상태
API 키3생성, 목록, 삭제
앱6앱 관리 + 스토어 연동 상태
상품6상품 + 가격 관리
권한 (Entitlement)7권한 CRUD + 상품 연결
오퍼링 + 패키지8오퍼링/패키지 관리 + 상품 연결
페이월5결제 화면 설정
웹훅5이벤트 알림 관리
고객2고객 목록 + 상세
지표 + 차트3MRR, 이탈률 등 21종 차트
실험 (A/B)7A/B 테스트 + 변형 관리
구독자 (SDK)6구독자 관리 + 영수증
SDK API4오퍼링 조회 + 이벤트 기록

보안

  • JWT 자동 관리: 토큰 만료 시 자동 갱신, 401 응답 시 재시도
  • 입력 검증: 경로 탐색(path traversal) 방지, ID 인젝션 차단
  • 자격 정보 보호: AI에게 반환되는 에러 메시지에서 API 키, 비밀번호, 이메일이 자동 마스킹됩니다

주의: 주의: MCP 설정 파일에 비밀번호와 API 키가 포함됩니다. 이 파일을 Git에 커밋하지 않도록 .gitignore에 추가하세요.

다음 단계

  • REST API — MCP 도구가 호출하는 API 엔드포인트를 확인합니다.
  • 스토어 연동 — App Store Connect / Google Play Console 설정 방법을 확인합니다.
  • SDK 연동 — iOS/Android 앱에 SubX SDK를 연동합니다.
MCP 연동 | SubX