Claude Code 플러그인으로 Spotify Ads API 자연어 인터페이스 구축

Spotify가 30개 넘는 리소스 타입과 중첩 타겟팅 구조를 가진 복잡한 Ads API v3를 자연어로 다루게 만든 Claude Code 플러그인 사례다. "코네티컷 25-44세, 일 $100 예산 캠페인 만들어줘" 같은 문장을 올바른 다단계 API 호출 시퀀스로 변환하는 것이 목표다.

핵심 포인트

광고 캠페인은 캠페인에서 광고세트, 광고로 이어지는 계층 생성, 단계별 ID 전달, 달러에서 마이크로 단위 변환, 지역 타겟 ID 조회를 요구해 사용자 의도와 실제 호출 사이 인지 거리가 크다.
MCP는 API surface가 너무 커 정적 도구 정의로 표현이 안 되고 매 상호작용마다 컨텍스트 윈도우를 낭비해 채택하지 않았다.
대신 Claude Code를 택해 모든 구성요소를 Markdown으로 두고 빌드 단계를 없앴으며, API 변경 시 OpenAPI 스펙 한 파일만 고치면 되고 모든 curl 호출이 사용자에게 그대로 보인다.
의존성은 curl, jq, python3 셋뿐이고 OpenAPI 스펙은 약 8,600줄이다.

상세 정리

문제: Ads API v3는 리소스 30여 종에 중첩 스키마와 다단계 엔티티 계층을 갖춰 사람이 직접 호출을 조립하기 어렵다.
MCP 기각 사유: 수십 개 엔드포인트와 중첩 스키마를 정적 tool 정의로 다 담을 수 없고 스펙 유지 비용과 컨텍스트 낭비가 크다.
Claude Code 선택 사유: 전부 Markdown이라 컴파일·빌드가 없고, 변경은 스펙 파일 단일 수정으로 끝나며, curl 명령이 노출돼 복사·검증·독립 실행이 가능하다.
4계층 구조: Skills는 Markdown 슬래시 커맨드로 엔드포인트와 요청 포맷과 출력 처리를, Agents는 Markdown으로 자연어 분해와 호출 순서화를, Hooks는 Python PreToolUse로 OAuth 토큰 갱신과 헤더 주입을, Settings는 gitignored 로컬 자격증명과 광고 계정과 환경을 담는다.
에이전트 로직: 값 변환($100을 100000000 마이크로로, "내일"을 ISO 8601로), 캠페인 생성 시 campaign에서 ad_set, ad로 3연속 호출 오케스트레이션, /targets/geos 조회로 지역 타겟 구조 생성, audience_estimate로 최소 임계값 사전 검증을 수행한다.
OpenAPI Links 활용: 캠페인 201 응답의 id를 광고세트 요청의 campaign_id로 넘기는 식으로 엔티티 계층을 스펙에 인코딩해 에이전트가 워크플로 그래프를 스스로 추론한다.
문서 이원화: 가장 흔한 작업은 큐레이션된 레퍼런스로, 모든 엔드포인트·엣지 케이스·에러는 raw 스펙으로 나눠 제공한다.
실행 제어: auto_execute 설정에 따라 curl을 먼저 보여주고 확인받거나 바로 실행한다.
한계와 로드맵: 매우 복잡한 API 통합으로 확장될지는 미지수이며, 재시도·재실행 중복을 막는 멱등성 키, Gemini CLI 등 멀티플랫폼, 이미지 생성을 계획한다.
배포: Apache 2.0 오픈소스로 GitHub와 Claude Plugins 마켓플레이스에 공개했다.

왜 읽나복잡한 내부 API를 LLM 에이전트로 감싸려는 플랫폼 엔지니어에게 MCP 대신 Claude Code와 OpenAPI로 가는 설계 판단과 계층 구성을 준다.

Spotify Engineering 블로그

원문은 여기서 이어서 읽을 수 있어요

원문 읽기

읽음 (0)

·takedown 요청

Claude Code 플러그인으로 Spotify Ads API 자연어 인터페이스 구축

이 글과 비슷한

학습 에이전트 — AI 두뇌 구축하기

AI 에이전트 회사 차리기: 설립부터 어디서든 동기화까지

AI Gateway에서 실시간 음성 에이전트 구축하기