AI 에이전트에게 결제 연동을 맡기는 법 (Remote MCP)

구독결제 연동은 코드 몇 줄이지만, 요금제 설계·API Key 발급·웹훅 등록 같은 준비 작업은 여전히 사람이 대시보드를 오가며 처리해야 했습니다. 슈퍼빌링은 이 과정 전체를 AI 에이전트에게 맡길 수 있는 Remote MCP 엔드포인트를 제공합니다.

MCP란

MCP(Model Context Protocol)는 AI 에이전트가 외부 서비스의 기능을 "도구(tool)"로 호출할 수 있게 해주는 표준 프로토콜입니다. Claude 같은 에이전트에게 "우리 서비스에 Pro/Team 요금제를 만들고 구독 결제를 연동해줘"라고 지시하면, 에이전트가 직접 API Key로 인증해 요금제 생성부터 구독 관리까지 처리합니다. 대시보드를 열고 클릭할 필요가 없습니다.

실제 동작 예시

에이전트에게 다음처럼 지시하면:

> "Pro 요금제(월 2만9천원)와 Team 요금제(월 9만9천원)를 만들고, 웹훅 엔드포인트로 https://myapp.com/webhooks/superbilling를 등록해줘."

에이전트는 내부적으로 create_plan을 두 번, register_webhook을 한 번 호출합니다. register_webhook이 반환하는 시크릿은 서명 검증에 필요하므로, 에이전트가 이 값을 대화 맥락에 노출하지 않고 .env 같은 안전한 위치에 저장하도록 프롬프트에 명시해두는 걸 권장합니다.

제공하는 도구(19개)

Plans/Customers/Subscriptions/Invoices/Payments/Webhooks 전 영역을 다룹니다. 정확한 입력 스키마는 MCP tools/list로 항상 조회 가능하며, 전체 목록은 MCP 연동 문서에 정리돼 있습니다.

• Plans: list_plans, create_plan, update_plan, delete_plan
• Customers: list_customers, create_customer, update_customer, delete_customer
• Subscriptions: list_subscriptions, create_subscription, cancel_subscription, reactivate_subscription
• Invoices/Payments: list_invoices, get_invoice, list_payments, get_payment
• Webhooks: list_webhooks, register_webhook, delete_webhook

별도 인증 체계가 필요 없는 이유 — 그리고 그 트레이드오프

MCP 스펙 자체는 원격 서버에 OAuth 인증을 권장하지만, 슈퍼빌링 MCP 엔드포인트는 새로운 인증 방식을 추가하지 않고 기존 API Key 인증을 그대로 재사용합니다. OAuth나 별도 스코프 체계를 새로 설계하지 않은 이유는 단순합니다 — API Key만으로 충분히 검증된 뒤에야 추가 복잡성이 필요한지 판단할 수 있기 때문입니다.

다만 이 선택에는 명확한 트레이드오프가 있습니다: 현재 API Key는 곧 테넌트 전체 권한입니다. 읽기 전용 키나 특정 리소스에만 접근 가능한 스코프 제한 기능은 아직 없습니다. 즉 에이전트에게 MCP 접속 정보를 넘기는 순간, 그 에이전트는 REST API로 할 수 있는 모든 일(요금제 삭제, 구독 해지 포함)을 할 수 있습니다.

결제 도메인에서 에이전트에게 전체 권한을 줄 때 주의할 점

결제·구독 데이터는 실수의 대가가 큰 영역입니다. 에이전트가 프롬프트 인젝션(악의적 콘텐츠에 숨겨진 지시)에 노출되거나 지시를 잘못 해석하면, 의도치 않은 구독 취소나 잘못된 요금제 생성으로 이어질 수 있습니다. 현재 슈퍼빌링 MCP는 도구 호출 전 별도 확인 단계(human-in-the-loop 승인)를 자체적으로 강제하지 않으므로, 다음을 권장합니다.

• 프로덕션 테넌트가 아닌 테스트 테넌트에서 먼저 에이전트 워크플로를 검증하세요.
• 사용하는 MCP 클라이언트(Claude Code, Claude Desktop 등)가 지원하는 "도구 호출 전 확인" 옵션을 켜두세요.
• API Key는 대시보드 `/dashboard/api-keys`에서 언제든 폐기(revoke)할 수 있고, 마지막 사용 시각(lastUsedAt)이 기록되므로 의심스러운 활동은 여기서 먼저 확인하세요.

연동 방법

Claude Code라면 다음 한 줄로 등록합니다.

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

Claude Desktop 등 다른 클라이언트의 설정 예시와 알려진 제약사항(자동 청구는 정액제만 지원, 구독 이력 있는 리소스는 FK 제약으로 삭제 불가 등)은 MCP 연동 문서에서 확인하세요.

정리

"가입만 하면 설정 없이 AI 에이전트에게 전부 맡길 수 있다"는 것이 슈퍼빌링이 다른 구독결제 SaaS와 차별화되는 지점입니다. 다만 API Key가 테넌트 전체 권한을 가진다는 점을 인지하고, 스코프 제한이 필요한 프로덕션 환경에서는 테스트 테넌트로 먼저 검증한 뒤 적용하는 걸 권장합니다. 스코프 제한 기능 자체는 저희도 다음 개선 과제로 검토 중입니다.