
Get details for a Spotify album by ID. Returns album name, artists, tracks, release date, genres, and more.
List tracks in a Spotify album with pagination. Use offset from page_info to fetch next page.
Get details for a Spotify artist by ID. Returns name, genres, popularity, followers, and images.
List albums by a Spotify artist with pagination. Filter by includegroups (album, single, appearson, compilation).
Get details for a Spotify audiobook by ID. Returns name, authors, narrators, publisher, chapters, and more.
List chapters of a Spotify audiobook with pagination. Use offset from page_info for next page.
Get details for a Spotify audiobook chapter by ID. Returns name, description, duration, chapter number, and more.
Get details for a Spotify episode by ID. Returns name, description, duration, release date, show info, and more.
Follow artists or users on Spotify. Provide type ('artist' or 'user') and list of Spotify IDs.
Unfollow artists or users on Spotify. Provide type ('artist' or 'user') and list of Spotify IDs.
List artists the user follows. Cursor-based pagination: use 'after' from page_info.cursor for next page.
List the current user's saved tracks with pagination. Use offset from page_info for next page.
List the current user's saved albums with pagination. Use offset from page_info for next page.
List the current user's saved shows/podcasts with pagination. Use offset from page_info for next page.
List the current user's saved episodes with pagination. Use offset from page_info for next page.
List the current user's saved audiobooks with pagination. Use offset from page_info for next page.
Save tracks, albums, shows, episodes, or audiobooks to the user's library. Provide type and list of IDs (max 50).
Remove tracks, albums, shows, episodes, or audiobooks from the user's library. Provide type and list of IDs.
Check if tracks, albums, shows, episodes, or audiobooks are saved in the user's library. Returns {id, is_saved} for each.
Get the current playback state including device, repeat/shuffle mode, playing item, and progress.
Get the user's available Spotify devices. Returns device ID, name, type, volume, and active status.
Get the currently playing track or episode. Returns None if nothing is playing.
Get the user's playback queue. Returns the currently playing item and upcoming items in the queue.
Start or resume playback. Requires Spotify Premium. Provide contexturi (album/playlist) or uris (track list). Use getdevices to find device_id.
Pause playback on the active device. Requires Spotify Premium. Use getdevices to find deviceid.
Skip to the next track. Requires Spotify Premium.
Skip to the previous track. Requires Spotify Premium.
Seek to a position in the current track. Requires Spotify Premium. Position is in milliseconds.
Set repeat mode: 'track' (repeat current), 'context' (repeat album/playlist), or 'off'. Requires Premium.
Enable or disable shuffle mode. Requires Spotify Premium.
Set playback volume (0-100). Requires Spotify Premium. Not available on all devices.
Add a track or episode to the playback queue. Requires Premium. URI format: spotify:track:ID or spotify:episode:ID.
Transfer playback to another device. Requires Premium. Use getdevices to find device IDs. Pass single deviceid in list.
Get details for a Spotify playlist by ID. Returns name, description, owner, tracks, and images.
List the current user's playlists with pagination. Use offset from page_info for next page.
Create a new playlist for the current user. Returns the created playlist with ID and URI.
Update a playlist's name, description, or visibility. Use get_playlist to verify changes.
List items (tracks/episodes) in a playlist with pagination. Use offset from page_info for next page.
Add tracks/episodes to a playlist. Provide URIs in spotify:track:ID or spotify:episode:ID format. Returns snapshot_id.
Remove tracks/episodes from a playlist by URI. Provide URIs in spotify:track:ID format. Returns snapshot_id.
Reorder items in a playlist. Move rangelength items starting at rangestart to insert_before position.
Search Spotify for tracks, albums, artists, playlists, shows, episodes, or audiobooks. Specify types as comma-separated string. Supports field filters like artist:name, album:name.
Get details for a Spotify show/podcast by ID. Returns name, description, publisher, total episodes, and more.
List episodes of a Spotify show/podcast with pagination. Use offset from page_info for next page.
Get details for a Spotify track by ID. Returns track name, artists, album, duration, popularity, and more.
Get the current user's Spotify profile. Returns display name, email, country, subscription level, and more.
Get the user's top artists or tracks based on listening history. Supports time ranges: shortterm (~4 weeks), mediumterm (~6 months), long_term (all time).
Get the user's recently played tracks. Cursor-based: use 'after' timestamp from page_info.cursor for next page.
Validate Spotify credentials by fetching the current user profile. Returns {success, message}.

In an mcp.json file, add the configuration below, and restart Cursor.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5 "headers": {
6 "Authorization": "Bearer yMt*****"
7 }
8 }
9 }
10}
11Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.
Make sure Claude is using the Node v20+.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "command": "npx",
5 "args": [
6 "-y",
7 "mcp-remote@latest",
8 "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9 "--header",
10 "Authorization: Bearer ${AUTH_TOKEN}"
11 ],
12 "env": {
13 "AUTH_TOKEN": "yMt*****"
14 }
15 }
16 }
17}Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "command": "npx",
5 "args": [
6 "-y",
7 "mcp-remote@latest",
8 "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9 "--header",
10 "Authorization: Bearer ${AUTH_TOKEN}"
11 ],
12 "env": {
13 "AUTH_TOKEN": "<ah-production-access-key>"
14 }
15 }
16 }
17 }In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".
You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.
Learn more in the official documentation ↗
1{
2 "inputs": [
3 {
4 "type": "promptString",
5 "id": "agent-handler-auth",
6 "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7 "password": true
8 }
9 ],
10 "servers": {
11 "agent-handler": {
12 "type": "stdio",
13 "command": "npx",
14 "args": [
15 "-y",
16 "mcp-remote@latest",
17 "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18 "--header",
19 "Authorization: Bearer ${input:agent-handler-auth}"
20 ]
21 }
22 }
23}It's an MCP server that connects your agents to Spotify's music platform via tools. Your agents can invoke these tools to search for music, control playback, manage playlists, access listening history, and more.
Spotify doesn't offer an official MCP server, but you can use one from a third-party platform, like Merge Agent Handler.
The use cases naturally depend on the agent you've built, but here are a few common ones:
Here are some of the most commonly used tools:
search: searches Spotify for tracks, artists, albums, playlists, or podcasts matching a text query. Use this when an agent needs to find specific music content before adding it to a queue, playlist, or playback sessionstart_playback: begins or resumes playback on a specified device, optionally targeting a track, album, or playlist URI. Call this when an agent needs to trigger music in response to a user action or a scheduled workflow eventcreate_playlist: creates a new Spotify playlist for the current user with a name, description, and visibility setting. Use this when an agent is assembling a curated set of tracks and needs a destination to collect themadd_playlist_items: adds one or more tracks to an existing Spotify playlist by URI. Good for agents that build playlists incrementally from search results, user preferences, or external recommendation dataget_currently_playing: returns the track currently playing on the user's Spotify account, including track name, artist, and playback state. Helpful when an agent needs to check what's active before making a queue management or logging decisionget_user_top_items: returns the user's top tracks or artists over a short, medium, or long time range. Use this when an agent needs to personalize recommendations or generate a listening summary based on real listening behaviorSpotify doesn't have an official MCP server, so if you're choosing between a community implementation and a managed platform, here's what differentiates Merge Agent Handler:
You can take the following steps:
1. Create or log into your Merge Agent Handler account and navigate to Tool Packs (collections of connector tools scoped to a specific use case).
2. Create a new Tool Pack, then find and enable the Spotify connector. Match tools to your use case. For example, use search and get_user_top_items for discovery and reporting, and use tools like start_playback, create_playlist, and add_playlist_items to control playback or manage music libraries.
3. Add a Registered User inside the Tool Pack. This is the identity context under which your agent operates. Merge generates a unique MCP URL scoped to this user once it's created.
4. From the Registered User detail page, authenticate Spotify by completing the OAuth flow. Merge stores and manages the credentials going forward.
5. Copy the MCP URL from the Tool Pack detail page and generate an API key from Settings. You'll need both to connect your agent.
6. Add the MCP server to your agent or IDE using the MCP URL and API key. Your Spotify tools are now accessible through that endpoint.
Whether you're an engineer experimenting with agents or a product manager looking to add tools, you can get started for free now