How to integrate Spotify MCP with Vercel AI SDK v6

Connect Vercel AI SDK v6 to Spotify MCP. Add these songs to your running playlist, check if i follow taylor swift, and more using natural language, with authentication handled for you.

Spotify logoSpotify
Oauth2

Spotify is a streaming service for music and podcasts with millions of tracks from artists worldwide. Enjoy personalized playlists, recommendations, and seamless listening across all your devices.

84 Tools3 Triggers

Introduction

This guide walks you through connecting Spotify to Vercel AI SDK v6 using the Composio tool router. By the end, you'll have a working Spotify agent that can control playback, create and edit playlists, search music and podcasts, save tracks to your library, and check your top artists through natural language commands.

This guide will help you understand how to give your Vercel AI SDK agent real control over a Spotify account through Composio's Spotify MCP server.

Before we dive in, let's take a quick look at the key ideas and tools involved.

For exact tool slugs and parameter tables, see the tool catalog in the Composio docs.

Also integrate Spotify with

TL;DR

Here's what you'll learn:
  • How to set up and configure a Vercel AI SDK agent with Spotify integration
  • Using Composio's Tool Router to dynamically load and access Spotify tools
  • Creating an MCP client connection using HTTP transport
  • Building an interactive CLI chat interface with conversation history management
  • Handling tool calls and results within the Vercel AI SDK framework

What is Vercel AI SDK?

The Vercel AI SDK is a TypeScript library for building AI-powered applications. It provides tools for creating agents that can use external services and maintain conversation state.

Key features include:

  • streamText: Core function for streaming responses with real-time tool support
  • MCP Client: Built-in support for Model Context Protocol via @ai-sdk/mcp
  • Step Counting: Control multi-step tool execution with stopWhen: stepCountIs()
  • OpenAI Provider: Native integration with OpenAI models

What is the Spotify MCP server, and what's possible with it?

The Spotify MCP server is an implementation of the Model Context Protocol that connects your AI agent and assistants like Claude, Cursor, etc directly to your Spotify account. It provides structured and secure access to your playlists, music library, and playback controls, so your agent can perform actions like managing playlists, adding songs to your queue, checking saved tracks, and updating playlist details on your behalf.

  • Personalized playlist management: Let your agent add songs or podcasts to playlists, change playlist details like name or privacy settings, and keep your music organized just how you like it.
  • Playback control and queue updates: Direct your agent to add tracks or episodes to your current playback queue, helping you line up the perfect listening experience without lifting a finger.
  • Library checks and smart recommendations: Have your agent check if specific tracks, albums, shows, or audiobooks are already saved in your Spotify library, so you never add duplicates or miss out on favorites.
  • Social and follower insights: Ask your agent to check whether you or others are following certain artists, users, or playlists, making it easy to stay connected to your musical community.
  • Podcast and show management: Let your agent verify which podcast episodes or shows are in your library, ensuring you’re always up to date with your latest audio interests.

What is the Composio tool router, and how does it fit here?

What is Composio SDK?

Composio's Composio SDK helps agents find the right tools for a task at runtime. You can plug in multiple toolkits (like Gmail, HubSpot, and GitHub), and the agent will identify the relevant app and action to complete multi-step workflows. This can reduce token usage and improve the reliability of tool calls. Read more here: Getting started with Composio SDK

The tool router generates a secure MCP URL that your agents can access to perform actions.

How the Composio SDK works

The Composio SDK follows a three-phase workflow:

  1. Discovery: Searches for tools matching your task and returns relevant toolkits with their details.
  2. Authentication: Checks for active connections. If missing, creates an auth config and returns a connection URL via Auth Link.
  3. Execution: Executes the action using the authenticated connection.

Step-by-step Guide

Step by step09 STEPS
1

Prerequisites

Before you begin, make sure you have:
  • Node.js and npm installed
  • A Composio account with API key
  • An OpenAI API key
2

Getting API Keys for OpenAI and Composio

OpenAI API Key
  • Go to the OpenAI dashboard and create an API key. You'll need credits to use the models, or you can connect to another model provider.
  • Keep the API key safe.
Composio API Key
  • Log in to the Composio dashboard.
  • Navigate to your API settings and generate a new API key.
  • Store this key securely as you'll need it for authentication.
3

Install required dependencies

bash
npm install @ai-sdk/openai @ai-sdk/mcp @composio/core ai dotenv

First, install the necessary packages for your project.

What you're installing:

  • @ai-sdk/openai: Vercel AI SDK's OpenAI provider
  • @ai-sdk/mcp: MCP client for Vercel AI SDK
  • @composio/core: Composio SDK for tool integration
  • ai: Core Vercel AI SDK
  • dotenv: Environment variable management
4

Set up environment variables

bash
OPENAI_API_KEY=your_openai_api_key_here
COMPOSIO_API_KEY=your_composio_api_key_here
COMPOSIO_USER_ID=your_user_id_here

Create a .env file in your project root.

What's needed:

  • OPENAI_API_KEY: Your OpenAI API key for GPT model access
  • COMPOSIO_API_KEY: Your Composio API key for tool access
  • COMPOSIO_USER_ID: A unique identifier for the user session
5

Import required modules and validate environment

typescript
import "dotenv/config";
import { openai } from "@ai-sdk/openai";
import { Composio } from "@composio/core";
import * as readline from "readline";
import { streamText, type ModelMessage, stepCountIs } from "ai";
import { createMCPClient } from "@ai-sdk/mcp";

const composioAPIKey = process.env.COMPOSIO_API_KEY;
const composioUserID = process.env.COMPOSIO_USER_ID;

if (!process.env.OPENAI_API_KEY) throw new Error("OPENAI_API_KEY is not set");
if (!composioAPIKey) throw new Error("COMPOSIO_API_KEY is not set");
if (!composioUserID) throw new Error("COMPOSIO_USER_ID is not set");

const composio = new Composio({
  apiKey: composioAPIKey,
});
What's happening:
  • We're importing all necessary libraries including Vercel AI SDK's OpenAI provider and Composio
  • The dotenv/config import automatically loads environment variables
  • The MCP client import enables connection to Composio's tool server
6

Create Tool Router session and initialize MCP client

typescript
async function main() {
  // Create a tool router session for the user
  const session = await composio.create(composioUserID!, {
    toolkits: ["spotify"],
  });

  const mcpUrl = session.mcp.url;
What's happening:
  • We're creating a Tool Router session that gives your agent access to Spotify tools
  • The create method takes the user ID and specifies which toolkits should be available
  • The returned mcp object contains the URL and authentication headers needed to connect to the MCP server
  • This session provides access to all Spotify-related tools through the MCP protocol
7

Connect to MCP server and retrieve tools

typescript
const mcpClient = await createMCPClient({
  transport: {
    type: "http",
    url: mcpUrl,
    headers: session.mcp.headers, // Authentication headers for the Composio MCP server
  },
});

const tools = await mcpClient.tools();
What's happening:
  • We're creating an MCP client that connects to our Composio Tool Router session via HTTP
  • The mcp.url provides the endpoint, and mcp.headers contains authentication credentials
  • The type: "http" is important - Composio requires HTTP transport
  • tools() retrieves all available Spotify tools that the agent can use
8

Initialize conversation and CLI interface

typescript
let messages: ModelMessage[] = [];

console.log("Chat started! Type 'exit' or 'quit' to end the conversation.\n");
console.log(
  "Ask any questions related to spotify, like summarize my last 5 emails, send an email, etc... :)))\n",
);

const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout,
  prompt: "> ",
});

rl.prompt();
What's happening:
  • We initialize an empty messages array to maintain conversation history
  • A readline interface is created to accept user input from the command line
  • Instructions are displayed to guide the user on how to interact with the agent
9

Handle user input and stream responses with real-time tool feedback

typescript
rl.on("line", async (userInput: string) => {
  const trimmedInput = userInput.trim();

  if (["exit", "quit", "bye"].includes(trimmedInput.toLowerCase())) {
    console.log("\nGoodbye!");
    rl.close();
    process.exit(0);
  }

  if (!trimmedInput) {
    rl.prompt();
    return;
  }

  messages.push({ role: "user", content: trimmedInput });
  console.log("\nAgent is thinking...\n");

  try {
    const stream = streamText({
      model: openai("gpt-5"),
      messages,
      tools,
      toolChoice: "auto",
      stopWhen: stepCountIs(10),
      onStepFinish: (step) => {
        for (const toolCall of step.toolCalls) {
          console.log(`[Using tool: ${toolCall.toolName}]`);
          }
          if (step.toolCalls.length > 0) {
            console.log(""); // Add space after tool calls
          }
        },
      });

      for await (const chunk of stream.textStream) {
        process.stdout.write(chunk);
      }

      console.log("\n\n---\n");

      // Get final result for message history
      const response = await stream.response;
      if (response?.messages?.length) {
        messages.push(...response.messages);
      }
    } catch (error) {
      console.error("\nAn error occurred while talking to the agent:");
      console.error(error);
      console.log(
        "\nYou can try again or restart the app if it keeps happening.\n",
      );
    } finally {
      rl.prompt();
    }
  });

  rl.on("close", async () => {
    await mcpClient.close();
    console.log("\n👋 Session ended.");
    process.exit(0);
  });
}

main().catch((err) => {
  console.error("Fatal error:", err);
  process.exit(1);
});
What's happening:
  • We use streamText instead of generateText to stream responses in real-time
  • toolChoice: "auto" allows the model to decide when to use Spotify tools
  • stopWhen: stepCountIs(10) allows up to 10 steps for complex multi-tool operations
  • onStepFinish callback displays which tools are being used in real-time
  • We iterate through the text stream to create a typewriter effect as the agent responds
  • The complete response is added to conversation history to maintain context
  • Errors are caught and displayed with helpful retry suggestions

Complete Code

Here's the complete code to get you started with Spotify and Vercel AI SDK:

typescript
import "dotenv/config";
import { openai } from "@ai-sdk/openai";
import { Composio } from "@composio/core";
import * as readline from "readline";
import { streamText, type ModelMessage, stepCountIs } from "ai";
import { createMCPClient } from "@ai-sdk/mcp";

const composioAPIKey = process.env.COMPOSIO_API_KEY;
const composioUserID = process.env.COMPOSIO_USER_ID;

if (!process.env.OPENAI_API_KEY) throw new Error("OPENAI_API_KEY is not set");
if (!composioAPIKey) throw new Error("COMPOSIO_API_KEY is not set");
if (!composioUserID) throw new Error("COMPOSIO_USER_ID is not set");

const composio = new Composio({
  apiKey: composioAPIKey,
});

async function main() {
  // Create a tool router session for the user
  const session = await composio.create(composioUserID!, {
    toolkits: ["spotify"],
  });

  const mcpUrl = session.mcp.url;

  const mcpClient = await createMCPClient({
    transport: {
      type: "http",
      url: mcpUrl,
      headers: session.mcp.headers, // Authentication headers for the Composio MCP server
    },
  });

  const tools = await mcpClient.tools();

  let messages: ModelMessage[] = [];

  console.log("Chat started! Type 'exit' or 'quit' to end the conversation.\n");
  console.log(
    "Ask any questions related to spotify, like summarize my last 5 emails, send an email, etc... :)))\n",
  );

  const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout,
    prompt: "> ",
  });

  rl.prompt();

  rl.on("line", async (userInput: string) => {
    const trimmedInput = userInput.trim();

    if (["exit", "quit", "bye"].includes(trimmedInput.toLowerCase())) {
      console.log("\nGoodbye!");
      rl.close();
      process.exit(0);
    }

    if (!trimmedInput) {
      rl.prompt();
      return;
    }

    messages.push({ role: "user", content: trimmedInput });
    console.log("\nAgent is thinking...\n");

    try {
      const stream = streamText({
        model: openai("gpt-5"),
        messages,
        tools,
        toolChoice: "auto",
        stopWhen: stepCountIs(10),
        onStepFinish: (step) => {
          for (const toolCall of step.toolCalls) {
            console.log(`[Using tool: ${toolCall.toolName}]`);
          }
          if (step.toolCalls.length > 0) {
            console.log(""); // Add space after tool calls
          }
        },
      });

      for await (const chunk of stream.textStream) {
        process.stdout.write(chunk);
      }

      console.log("\n\n---\n");

      // Get final result for message history
      const response = await stream.response;
      if (response?.messages?.length) {
        messages.push(...response.messages);
      }
    } catch (error) {
      console.error("\nAn error occurred while talking to the agent:");
      console.error(error);
      console.log(
        "\nYou can try again or restart the app if it keeps happening.\n",
      );
    } finally {
      rl.prompt();
    }
  });

  rl.on("close", async () => {
    await mcpClient.close();
    console.log("\n👋 Session ended.");
    process.exit(0);
  });
}

main().catch((err) => {
  console.error("Fatal error:", err);
  process.exit(1);
});

Conclusion

You've successfully built a Spotify agent using the Vercel AI SDK with streaming capabilities! This implementation provides a powerful foundation for building AI applications with natural language interfaces and real-time feedback.

Key features of this implementation:

  • Real-time streaming responses for a better user experience with typewriter effect
  • Live tool execution feedback showing which tools are being used as the agent works
  • Dynamic tool loading through Composio's Tool Router with secure authentication
  • Multi-step tool execution with configurable step limits (up to 10 steps)
  • Comprehensive error handling for robust agent execution
  • Conversation history maintenance for context-aware responses

You can extend this further by adding custom error handling, implementing specific business logic, or integrating additional Composio toolkits to create multi-app workflows.
TOOLS & TRIGGERS

Supported Tools and Triggers

Every Spotify action and event your agent gets out of the box.

Add items to playlist

Add one or more items to a user's playlist.

Add item to playback queue

Add an item to the end of the user's current playback queue.

Change playlist details

Change a playlist's name and public/private state.

Check if user follows artists or users

Check whether the current user follows up to 50 specified artists or Spotify users.

Check if users follow playlist

Check whether the authenticated user follows a specified public or owned Spotify playlist.

Check user s saved albums

Check whether up to 20 albums, identified by Spotify ID, are saved in the current user's library.

Check user s saved audiobooks

Check whether up to 50 audiobooks, identified by Spotify ID, are saved in the current user's library.

Check User's Saved Episodes

Check whether up to 50 podcast episodes by ID are saved in the current user's Your Episodes library.

Check user's saved shows

Check whether up to 50 shows, identified by Spotify ID, are saved in the current user's library.

Check User's Saved Tracks

Check whether up to 50 tracks, identified by Spotify track ID, are saved in the current user's library.

Create playlist

Create an empty playlist for a Spotify user, with a name and optional description, visibility, and collaboration settings.

Follow artists or users

Follow one or more artists or Spotify users by ID for the current authenticated user, adding them to the user's following list.

Follow playlist

Follow a playlist for the current Spotify user by playlist ID, publicly or privately.

Get a chapter

Get Spotify catalog information for a single audiobook chapter including name, description, duration, release date, narrators, and playback information.

Get Album Details

Get Spotify catalog information for a single album by ID, including metadata, track listing, artist information and cover artwork.

Get album tracks

Get Spotify catalog information about an album's tracks.

Get an audiobook

Get Spotify catalog information for a single audiobook.

Get artist

Get detailed Spotify catalog information for a single artist, including name, genres, profile images and Spotify links.

Get artist s albums

Get Spotify catalog information about an artist's albums.

Get artist s related artists

Get Spotify catalog information about artists similar to a given artist.

Get Artist's Top Tracks

Get Spotify catalog information about an artist's top tracks in a specified market, defaulting to the US.

Get audiobook chapters

Get Spotify catalog information about an audiobook's chapters.

Get Available Devices

Get information about the user's available Spotify Connect devices.

Get available markets

Get the list of markets where Spotify is available, as ISO 3166-1 alpha-2 country codes.

Get currently playing track

Get the object currently being played on the user's Spotify account.

Get current user s playlists

Get a paginated list of playlists owned or followed by the current Spotify user, with playlist metadata and pagination links.

Get current user s profile

Get profile information for the current authenticated Spotify user, including available display name, images and Spotify URIs.

Get episode

Get Spotify catalog information for a single podcast episode identified by its unique Spotify ID.

Get featured playlists

Get a list of Spotify's editorially curated featured playlists.

Get followed artists

Get a cursor-paginated list of artists followed by the current Spotify user using the after parameter; requires user-follow-read.

Get new releases

Get a page of new album releases featured by Spotify, such as those shown in Browse.

Get playback state

Get the current user's Spotify playback state, including the active device, current track or episode, progress, playback context, and repeat and shuffle settings.

Get playlist

Get metadata and available contents of a Spotify playlist, with optional field filtering.

Get playlist cover image

Get the current cover images associated with a playlist.

Get playlist items

Get a paginated list of tracks or episodes in a playlist, with optional response field filtering.

Get recently played tracks

Get tracks from the current user's recently played tracks.

Get recommendations

Get track recommendations based on seed artists, genres, and/or tracks.

Get several albums

Get Spotify catalog information for up to 20 albums by Spotify ID, optionally specifying a market.

Get several artists

Get Spotify catalog information for up to 50 artists in one request using their Spotify IDs.

Get several audiobooks

Get Spotify catalog information for up to 50 audiobooks by ID in a single request, optionally specifying a market.

Get several browse categories

List Spotify browse categories used to tag items, with locale and limit/offset pagination.

Get several chapters

Get Spotify catalog details for up to 50 audiobook chapters by ID, including chapter metadata and parent audiobook information.

Get several episodes

Get Spotify catalog information for up to 50 episodes by their IDs in a single request, with an optional market.

Get several shows

Get Spotify catalog information for up to 50 shows by ID in a single request, optionally specifying a market.

Get several tracks

Get Spotify catalog information for multiple tracks by Spotify ID, with an optional market.

Get show

Get Spotify catalog information for a single show (podcast) identified by its unique Spotify ID.

Get show episodes

Get Spotify catalog information about a show's episodes.

Get single browse category

Get information about a Spotify browse category by ID, including its name and icons, with an optional locale.

Get the user's queue

Get the list of tracks and episodes in the user's playback queue.

Get track

Get Spotify catalog information for a single track identified by its unique Spotify ID.

Get Track's Audio Analysis

Get a comprehensive audio analysis for a Spotify track.

Get user's playlists

Get a paginated list of playlists owned or followed by a specified Spotify user, using limit and offset.

Get user's profile

Retrieve public profile information for a Spotify user by user ID, such as their display name and profile images.

Get user s saved albums

Get a list of albums saved in the current Spotify user's library ('Your Music').

Get user s saved audiobooks

Get a list of the audiobooks saved in the current Spotify user's 'Your Music' library.

Get user's saved episodes

Get a list of episodes saved in the current Spotify user's library.

Get User's Saved Shows

Get a list of shows saved in the current Spotify user's library.

Get User's Saved Tracks

Get a list of the songs saved in the current Spotify user's 'Your Music' library.

Get User's Top Artists

Get a paginated list of the current user's top artists based on listening affinity over a selected time range; requires user-top-read.

Get User's Top Tracks

Get the current user's top tracks based on listening affinity over a selected time range.

Pause playback

Pause playback on the user's account.

Remove playlist items

Remove one or more items from a user's playlist.

Remove users saved albums

Remove one or more albums from the current user's saved library.

Remove User's Saved Audiobooks

Remove one or more saved audiobooks from the current user's Spotify library by ID.

Remove user's saved episodes

Remove up to 50 episodes by ID from the current user's Your Episodes library; removing an unsaved episode succeeds.

Remove user s saved shows

Remove one or more shows by Spotify ID from the current user's library.

Remove user s saved tracks

Remove one or more tracks by Spotify ID from the current user's library.

Save albums for current user

Save one or more albums by Spotify ID to the current user's library.

Save audiobooks for current user

Save up to 50 audiobooks by Spotify ID to the current user's library for later access.

Save episodes for current user

Save up to 50 podcast episodes by Spotify ID to the current user's Your Episodes library for later playback.

Save shows for current user

Save up to 50 shows by Spotify ID to the current user's library.

Save tracks for current user

Save tracks to the current user's Spotify library using up to 50 track IDs or timestamped IDs.

Search for item

Search Spotify's catalog for albums, artists, playlists, tracks, shows, episodes or audiobooks matching a keyword.

Seek to position

Seek to a position in milliseconds in the user's currently playing track, targeting a specified device or the active device by default.

Set playback volume

Set the volume for the user's current playback device.

Set repeat mode

Set the repeat mode for the user's playback.

Skip to next

Skips to next track in the user's queue.

Skip to previous

Skips to the previous track in the user's queue.

Start resume playback

Start playback of a context or list of tracks, or resume playback on a Spotify device.

Toggle playback shuffle

Toggle shuffle on or off for user's playback.

Transfer playback

Transfer playback to a new device and optionally begin playback.

Unfollow artists or users

Unfollow up to 50 artists or Spotify users by ID for the current user, removing them from the following list.

Unfollow playlist

Unfollow a playlist by ID for the current user, removing it from their followed playlists.

Update playlist items

Either replace all tracks in a playlist OR reorder existing tracks within it.

FAQ

Frequently asked questions

Start with Spotify.It takes 30 seconds.

Managed auth, hosted MCP servers, and every Spotify tool your agent needs.Free to start.

Start building