Building a Natural Language Interface to the Spotify Ads API with Claude Code Plugins | Spotify Engineering
The post describes an open-source Claude Code plugin that lets users manage Spotify advertising campaigns through natural-language requests. It translates high-level intent into validated, multi-step Spotify Ads API calls, handling targeting lookups, budget conversions, entity dependencies, and missing information. The authors favor a Markdown- and CLI-based design over MCP because it keeps the system transparent, lightweight, customizable, and grounded in Spotify’s OpenAPI specification. ## Natural-Language Campaign Creation - Users can request campaigns conversationally, such as creating an audio campaign targeting a specific age range and location with a daily budget. - The agent orchestrates the campaign lifecycle: - Creates the campaign. - Creates an ad set with targeting and budget. - Creates the ad and attaches creative assets. - It handles implementation details automatically: - Looks up geographic targeting IDs. - Converts dollar amounts into API micro-units. - Validates audience size. - Passes entity IDs between dependent API calls. - Prompts for missing required information. ## Claude Code Plugin Architecture - **Skills** provide slash commands, with each command defined in Markdown alongside its endpoints, request formats, and output behavior. - **Agents** interpret freeform requests and decompose them into the necessary API operations. - **Hooks** intercept tool calls to refresh OAuth tokens and inject HTTP headers. - **Settings** store local user configuration, including credentials, ad accounts, and environment preferences. - Because all components are human-readable Markdown, the plugin has no compilation, bundling, or package-management step. - API behavior can often be corrected by updating documentation or instructions rather than changing compiled code. ## CLI and OpenAPI Instead of MCP - The authors avoided MCP because the Spotify Ads API has more than 30 resource types and complex nested schemas. - Defining every endpoint as an MCP tool would create a large static registry and consume context even when most tools were irrelevant. - The plugin loads only the API documentation needed for a particular task. - API calls are issued as visible `curl` commands, allowing users to inspect, copy, modify, and reproduce them. - Spotify’s roughly 8,600-line OpenAPI v3 specification serves as the single source of truth. - Updating one bundled specification file is simpler than maintaining a separate translation into MCP schemas. ## Domain-Specific Agent Behavior - The request-builder agent is defined in `agents/spotify-ads-request-builder.md`. - It teaches the model Spotify-specific conversions, including: - Dollar values to micro-amounts. - Natural-language dates to ISO 8601. - Platform names to API enum values. - It performs multi-step orchestration for campaign, ad set, and ad creation. - It resolves locations such as “Connecticut” through geo-targeting search endpoints and builds the required `geo_targets` structure. - It performs pre-flight audience estimates to ensure targeting meets minimum size requirements. - It is designed to control execution carefully and validate requests before making changes that could affect advertising budgets. ## Practical Implication The plugin demonstrates that a large advertising API can be made approachable without hiding its mechanics. A Markdown-based Claude Code integration, backed by the official OpenAPI specification and transparent CLI requests, offers a practical balance between natural-language convenience, developer control, auditability, and maintainability.
Read original(opens in new tab)