logo
문서블로그요금제 빌더 체험하기

SuperBilling MCP

"가입만 하면 설정 없이 AI 에이전트에게 전부 맡길 수 있다" — SuperBilling은 별도 OAuth나 신규 계정 없이, 이미 발급받은 API Key 하나로 Remote MCP(Streamable HTTP)에 접속할 수 있습니다.

접속 정보

  • 엔드포인트: https://<your-domain>/api/mcp (로컬 개발: http://localhost:3000/api/mcp)
  • 인증: Authorization: Bearer <api_key> 헤더 (대시보드 `/dashboard/api-keys`에서 발급한 sb_live_... 키 그대로 사용)
  • 프로토콜: Streamable HTTP — 세션을 유지하지 않는 stateless 모드이므로 매 요청이 독립적으로 인증됩니다.

API Key를 처음 발급하면 대시보드에 위 접속 정보가 담긴 MCP 클라이언트 설정 JSON이 그 자리에서 바로 표시됩니다.

Claude Code에 연결

claude mcp add --transport http superbilling https://<your-domain>/api/mcp \
  --header "Authorization: Bearer <api_key>"

Claude Desktop에 연결

claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "superbilling": {
      "url": "https://<your-domain>/api/mcp",
      "headers": {
        "Authorization": "Bearer <api_key>"
      }
    }
  }
}

제공 툴 (19개)

API Key가 곧 테넌트 전체 권한이므로, MCP로 할 수 있는 일은 REST API와 동일합니다. 정확한 입력 스키마는 MCP tools/list로 항상 조회 가능하지만, 자주 쓰는 필드는 아래에 미리 적어둡니다.

Plans

  • list_plans — 인자 없음
  • create_plan — name(string), description?(string), billingCycle("monthly" | "yearly"), trialDays?(number), pricingModel({kind:"flat", amountKrw} | {kind:"usage", unitLabel, unitPriceKrw, includedUnits} | {kind:"seat", seatPriceKrw, includedSeats})
  • update_plan — planId(string) + create_plan의 필드를 전부 선택적으로
  • delete_plan — planId(string)

Customers

  • list_customers — 인자 없음
  • create_customer — externalRef(string, 고객사 쪽 식별자), email?(string)
  • update_customer — customerId(string) + externalRef?, email?
  • delete_customer — customerId(string)

Subscriptions

  • list_subscriptions — 인자 없음
  • create_subscription — planId(string), customerId(string)
  • cancel_subscription / reactivate_subscription — subscriptionId(string)

Invoices / Payments

  • list_invoices / list_payments — 인자 없음
  • get_invoice — invoiceId(string)
  • get_payment — paymentId(string)

Webhooks

  • list_webhooks — 인자 없음
  • register_webhook — url(string)
  • delete_webhook — webhookId(string)

register_webhook이 반환하는 secret은 이후 웹훅 서명 검증에 필요하니 에이전트가 대화 맥락 밖(예: .env)에 저장하도록 안내하세요. 대시보드에는 이 secret이 일부만 노출됩니다.

알려진 제약

  • 구독 이력이 있는 Plan/Customer는 FK 제약으로 삭제할 수 없습니다(REST API와 동일). 먼저 관련 구독을 해지해야 합니다.
  • 자동 청구(cron)는 현재 정액제(kind: "flat") 요금제만 지원합니다.
  • 실제 카드 등록·청구는 대시보드에서 Payple 결제수단을 등록해야 시작됩니다 — MCP 툴로는 카드 등록을 대신할 수 없습니다.