SubXDocs

MCP Integration

Connect the SubX MCP server to AI tools like Claude or Cursor to manage subscriptions through conversation alone. Product registration, offering configuration, customer lookup — no need to open the dashboard.

What is MCP? MCP (Model Context Protocol) is a standard that allows AI tools to directly call external service functions. SubX MCP provides 81 tools covering the entire SubX API.

Prerequisites

  • SubX account (email + password)
  • API key — generate from the API Keys menu in the dashboard
  • Node.js 20 or higher

Using with Claude Code

Add the following to your ~/.claude/settings.local.json file:

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"
      }
    }
  }
}

After updating the config, restart Claude Code to start using SubX tools.

Using with Cursor

Create a .cursor/mcp.json file in the project root:

.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"
      }
    }
  }
}

Environment Variables

VariableRequiredDescription
SUBX_EMAILDashboard modeLogin email
SUBX_PASSWORDDashboard modeLogin password
SUBX_API_KEYSDK modeAPI key (subscriber lookup, offerings, etc.)
SUBX_BASE_URLOptionalDefault: https://api.subx.dev — only change for custom deployments

Authentication Modes

  • Dashboard mode (email + password): Access all management tools — projects, apps, products, entitlements, offerings, and more.
  • SDK mode (API key): Access subscriber-facing tools — subscriber lookup, offering retrieval, receipt submission, etc.
  • Set both modes simultaneously to access all 81 tools.

Usage Examples

After connecting MCP, say this to your AI:

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

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

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

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

Full Setup Workflow

A complete flow for building a subscription system from scratch using only MCP tools:

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                 → 이벤트 알림 설정

Available Tools (81)

CategoryCountMain Features
Auth2Login, user info
Projects6CRUD + setup status
API Keys3Create, list, delete
Apps6App management + store integration status
Products6Product + price management
Entitlements7Entitlement CRUD + product linking
Offerings + Packages8Offering/package management + product linking
Paywalls5Payment screen configuration
Webhooks5Event notification management
Customers2Customer list + details
Metrics + Charts3MRR, churn rate, 21 chart types
Experiments (A/B)7A/B testing + variant management
Subscribers (SDK)6Subscriber management + receipts
SDK API4Offering retrieval + event recording

Security

  • Automatic JWT management: Auto-refresh on token expiry, retry on 401 response
  • Input validation: Path traversal prevention, ID injection protection
  • Credential protection: API keys, passwords, and emails are automatically masked in error messages returned to the AI

주의: Warning: MCP config files contain passwords and API keys. Add this file to .gitignore to prevent committing it to Git.

Next Steps

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