Building a Natural Language Interface to the Spotify Ads API with Claude Code Plugins

🖼️ 인포그래픽

Building a Natural Language Interface to the Spotify Ads API with Claude Code Plugins 내용을 설명하는 본문 이미지

🖼️ 4컷 인포그래픽

💡 한 줄 요약

Spotify는 복잡한 Ads API를 자연어 요청으로 다룰 수 있도록 Claude Code용 오픈소스 플러그인을 만들었고, Markdown 기반 지식·에이전트·OpenAPI 스펙·투명한 curl 실행을 결합해 광고 캠페인 생성 흐름을 자동화했다.

📌 핵심 요약

Spotify Ads API v3는 30개가 넘는 리소스 유형, 중첩된 타기팅 구조, 캠페인→광고 세트→광고로 이어지는 다단계 계층을 갖고 있어 단순한 광고 집행 의도도 여러 API 호출과 검증 절차로 분해해야 한다.
spotify-ads-api 플러그인은 Claude Code 안에서 자연어 요청을 해석해 지리 타기팅 ID 조회, 예산 단위 변환, 오디언스 규모 검증, 캠페인·광고 세트·광고 생성까지 필요한 API 호출 순서를 구성한다.
이 플러그인은 Skills, Agents, Hooks, Settings를 모두 Markdown 중심으로 구성해 빌드 단계나 패키지 관리 없이 사람이 읽고 수정하고 버전 관리할 수 있는 구조를 택했다.
Spotify는 MCP 대신 CLI와 OpenAPI 스펙 기반 접근을 선택했다. API 표면이 크고 정적 도구 정의가 방대해질 수 있으며, curl 명령을 사용자에게 보여주는 방식이 광고 예산에 영향을 주는 작업에서 투명성과 통제권을 제공한다고 봤기 때문이다.
OpenAPI Links는 캠페인 생성 응답의 ID를 광고 세트 생성 입력으로 넘기는 식의 작업 흐름 그래프를 명시해, 에이전트가 복수 API 호출을 올바른 순서로 연결하는 데 중요한 역할을 한다.

🧩 주요 포인트

Spotify Ads API v3는 30개가 넘는 리소스 유형, 중첩된 타기팅 구조, 캠페인→광고 세트→광고로 이어지는 다단계 계층을 갖고 있어 단순한 광고 집행 의도도 여러 API 호출과 검증 절차로 분해해야 한다.
spotify-ads-api 플러그인은 Claude Code 안에서 자연어 요청을 해석해 지리 타기팅 ID 조회, 예산 단위 변환, 오디언스 규모 검증, 캠페인·광고 세트·광고 생성까지 필요한 API 호출 순서를 구성한다.
이 플러그인은 Skills, Agents, Hooks, Settings를 모두 Markdown 중심으로 구성해 빌드 단계나 패키지 관리 없이 사람이 읽고 수정하고 버전 관리할 수 있는 구조를 택했다.
Spotify는 MCP 대신 CLI와 OpenAPI 스펙 기반 접근을 선택했다. API 표면이 크고 정적 도구 정의가 방대해질 수 있으며, curl 명령을 사용자에게 보여주는 방식이 광고 예산에 영향을 주는 작업에서 투명성과 통제권을 제공한다고 봤기 때문이다.
OpenAPI Links는 캠페인 생성 응답의 ID를 광고 세트 생성 입력으로 넘기는 식의 작업 흐름 그래프를 명시해, 에이전트가 복수 API 호출을 올바른 순서로 연결하는 데 중요한 역할을 한다.

🧠 상세 정리

1. 복잡한 광고 API와 자연어 인터페이스의 필요성

글은 Spotify Ads API가 강력하지만 사용하기 까다로운 이유에서 출발한다. API v3에는 30개가 넘는 리소스 유형이 있고, 타기팅 구조는 중첩되어 있으며, 캠페인 안에 광고 세트가 있고 광고 세트 안에 광고가 들어가는 다단계 계층을 따른다. 사용자가 단지 “코네티컷 청취자를 대상으로 오디오 캠페인을 시작하고 싶다”고 말하는 수준의 의도를 갖고 있어도, 실제 실행에는 여러 엔드포인트 호출과 올바른 파라미터 구성이 필요하다. Spotify 팀은 이 의도와 실행 사이의 인지적 거리를 줄이는 것을 목표로 삼았다. 그래서 사용자가 평범한 영어로 원하는 결과를 설명하면 시스템이 필요한 구조와 호출 순서를 알아서 구성하는 플러그인을 만들었다.

2. spotify-ads-api 플러그인의 기본 역할

결과물은 Claude Code 플러그인 형태의 spotify-ads-api이며, GitHub와 Anthropic의 Claude Plugins 마켓플레이스에서 제공된다. 이 플러그인은 Markdown 파일, bash 스크립트, 두 개의 작은 Python 헬퍼로 구성되어 자연어를 Spotify Ads API 호출로 변환한다. 개발자와 광고주가 LLM이 Ads API와 상호작용하는 방식을 직접 통제할 수 있도록 오픈소스로 공개된 점도 강조된다. 플러그인은 Claude Code에 설치되면 광고 캠페인을 관리하기 위한 slash command를 제공하고, 더 중요한 방식으로는 대화형 자연어 입력을 처리한다. 사용자는 여러 명령을 순서대로 입력하거나 오케스트레이션 코드를 작성하지 않고도 원하는 광고 결과를 말할 수 있다.

3. 자연어 요청을 실제 캠페인 생성 흐름으로 분해하는 방식

예시로 사용자는 “Back to School Promo라는 오디오 캠페인을 만들고, 미국의 25~44세를 대상으로 하며, 하루 예산은 100달러로 설정하라”고 요청할 수 있다. 플러그인의 에이전트는 이 문장을 단일 명령으로 취급하지 않고 필요한 API 단계로 분해한다. 먼저 지리 타기팅 ID를 조회하고, 달러 금액을 API가 요구하는 마이크로 단위로 변환하며, 오디언스 규모가 최소 기준을 충족하는지 검증한다. 이후 캠페인 엔티티를 만들고, 타기팅과 예산을 포함한 광고 세트를 생성한 다음, 크리에이티브 자산이 포함된 광고를 만든다. 필수 정보가 빠져 있으면 사용자에게 추가 질문을 던지는 방식으로 정확한 실행을 보장한다.

4. Claude Code와 Markdown 기반 플러그인 구조를 선택한 이유

Spotify 팀은 이 플러그인이 의도적으로 특정한 기술 선택을 했다고 설명한다. 가장 중요한 선택은 Claude Code였는데, 그 이유는 플러그인의 Skills, Agents, 참조 문서가 모두 Markdown 파일로 작성될 수 있다는 점이었다. 컴파일된 코드, 빌드 단계, 패키지 매니저, 번들러, 트랜스파일러가 필요하지 않기 때문에 구조가 단순하고 사람이 읽기 쉽다. Skills는 slash command의 동작, API 엔드포인트, 요청 형식, 출력 처리를 설명하고, Agents는 자유형 자연어 요청을 해석한다. Hooks는 도구 호출 전 OAuth 토큰을 갱신하고 HTTP 헤더를 주입하며, Settings는 사용자별 인증 정보와 광고 계정, 환경 설정을 gitignored 로컬 파일에 저장한다.

5. 사람이 읽고 수정할 수 있는 개발자 도구로서의 장점

Markdown 중심 구조의 장점은 모든 컴포넌트가 사람이 읽을 수 있고, diff로 비교할 수 있으며, 버전 관리가 쉽다는 데 있다. 테스트 중 API의 특이 동작이나 예외가 발견되면 전통적인 SDK처럼 코드를 대규모로 수정하기보다 Markdown 파일에 설명 한 문장을 추가하는 방식으로 대응할 수 있다. 이는 플러그인을 사용자 환경에 맞게 커스터마이즈하고 확장하며 적응시키는 비용을 낮춘다. Spotify 팀은 이 접근이 LLM이 API를 어떻게 이해하고 호출해야 하는지에 대한 비즈니스 로직을 문서화된 산문으로 유지하는 방식이라고 본다. 즉, 실행 가능한 통합 로직이 코드보다 문서와 지침에 더 가깝게 존재한다.

6. MCP 대신 CLI와 OpenAPI 스펙을 택한 판단

글은 Model Context Protocol이 LLM과 외부 도구를 연결하는 기본 표준으로 자리 잡아가고 있어 이 프로젝트에도 자연스러운 후보였다고 인정한다. 그러나 Spotify 팀은 MCP 서버로 각 캠페인 관리 기능을 도구화하는 방식 대신 CLI와 OpenAPI 스펙 기반 접근을 선택했다. Spotify Ads API의 엔드포인트와 중첩 스키마가 많아 이를 모두 MCP 도구로 정적으로 정의하면 방대한 도구 레지스트리가 만들어지고, 사용하지 않는 도구 정보까지 매 상호작용의 컨텍스트를 소비할 수 있기 때문이다. 반면 Claude Code 플러그인 방식은 요청에 필요한 참조 문서만 필요할 때 불러오게 할 수 있다. 또한 모든 API 호출이 사용자에게 curl 명령으로 표시되므로, 사용자는 무엇이 전송되는지 확인하고 복사·수정·재실행할 수 있다.

7. OpenAPI 스펙과 Links가 제공하는 워크플로 그래프

플러그인은 약 8,600줄 규모의 Spotify Ads API v3 OpenAPI 스펙을 함께 제공한다. 이 스펙은 문서이자 검증 수단이며, 에이전트가 필드 이름이나 타입을 확신하지 못할 때 관련 스키마를 확인하는 기준이 된다. 특히 글은 OpenAPI Links의 중요성을 강조한다. Links는 한 작업의 응답을 다른 작업의 입력으로 어떻게 사용할 수 있는지를 기계가 읽을 수 있게 정의한다. 캠페인 생성의 201 응답이 광고 세트 생성으로 이어지고, 광고 세트 생성 응답이 광고 생성 및 부모 캠페인과 연결되며, 광고 응답이 크리에이티브·이미지·로고 같은 자산과 연결되는 식이다. 이는 에이전트가 캠페인→광고 세트→광고 흐름을 따라 ID를 전달하는 데 직접적인 안내 역할을 한다.

8. 큐레이션된 문서와 원본 스펙의 상호 보완

Spotify 팀은 원본 OpenAPI 스펙만 제공하지 않고, api-reference skill을 통해 큐레이션된 엔드포인트 문서, 스키마 정의, enum 값을 함께 제공한다. 큐레이션된 문서는 자주 쓰는 작업을 명확한 예시와 함께 설명하고, 원본 스펙은 덜 쓰이는 엔드포인트, 예외적인 파라미터, 오류 응답까지 포괄한다. 에이전트는 먼저 사람이 읽기 쉽게 정리된 문서를 사용하고, 필요할 때 원본 스펙으로 내려가 세부 사항을 확인한다. 이 조합은 LLM이 흔한 광고 생성 흐름을 빠르게 처리하면서도, 낯선 요청이나 세부 검증이 필요한 상황에서 공식 스펙을 근거로 삼을 수 있게 한다. 결과적으로 문서 편의성과 전체 API 커버리지 사이의 실용적 균형을 취한다.

9. 향후 개선 방향과 안전장치

향후 계획으로는 사용자 흐름 관찰과 에이전트 로직 최적화가 제시된다. 현재 에이전트의 분해 로직은 비교적 단순한 광고 흐름에 대한 이해를 바탕으로 하며, 팀은 실제 사용 패턴과 분해 과정에서 병목이 생기는 지점을 관찰해 Markdown 기반 skills를 개선하려 한다. 사용자가 자주 보충 설명을 요구받는 부분을 파악하면, 시스템 프롬프트를 조정해 그런 엣지 케이스를 미리 처리할 수 있다. 또 하나의 계획은 idempotency key 지원이다. 네트워크 재시도나 에이전트 재실행 중 캠페인이나 광고가 중복 생성되는 문제를 막기 위해, 사용자 의도별 고유 클라이언트 키를 생성해 재시도 요청도 단일 작업으로 취급되게 하려는 것이다.

10. 투명한 실행을 중심에 둔 결론

마무리에서 글은 이 플러그인이 복잡한 API의 가장 좋은 인터페이스는 상세 문서에 근거한 자연어이며, 실행은 투명해야 한다는 가설에 기반한다고 정리한다. 사용자는 원하는 결과를 말하고, 에이전트는 필요한 API 호출을 구성하며, hook 계층은 인증을 조용히 처리한다. 동시에 모든 curl 명령은 보이고, 복사할 수 있으며, 디버깅할 수 있다. 플러그인에는 별도 프레임워크나 런타임, 복잡한 의존성이 없고 curl, jq, python3 정도만 필요하다고 설명된다. Spotify 팀은 이 접근이 모든 복잡한 API 통합에 확장될지는 열린 질문으로 남기지만, Spotify Ads API처럼 의도와 실제 POST 요청 시퀀스 사이의 거리가 큰 경우에는 인상적으로 잘 작동한다고 평가한다.

🧾 핵심 주장 / 시사점

이 글의 핵심은 LLM 통합을 ‘새로운 SDK 작성’이 아니라 ‘문서화된 실행 지침과 공식 스펙을 결합하는 문제’로 본다는 점이다.
광고 API처럼 실제 예산에 영향을 주는 시스템에서는 자동화 자체보다 사용자가 호출 내용을 볼 수 있고 재현할 수 있는 투명성이 중요한 설계 기준으로 제시된다.
OpenAPI Links를 단순 문서 보조 기능이 아니라 에이전트가 따라갈 수 있는 작업 그래프로 활용한 점은 다단계 API 워크플로 자동화에서 특히 실용적인 접근이다.

✅ 액션 아이템

복잡한 API를 자연어 인터페이스로 감싸기 전에, 자주 쓰는 작업 흐름과 실제 POST 요청 시퀀스를 OpenAPI Links 기준으로 정리한다.
사용자가 실행 내용을 검토할 수 있도록 모든 API 호출을 curl 명령으로 노출하고, OAuth 토큰 갱신과 헤더 주입은 hook 계층에서 처리한다.
원본 OpenAPI 스펙과 큐레이션된 Markdown 참조 문서를 함께 유지해, 흔한 작업은 빠르게 처리하고 낯선 요청은 공식 스키마로 검증한다.