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.