How to integrate Spotify MCP with Pydantic AI

Connect Pydantic AI 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 Pydantic AI 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 Pydantic AI 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 your Composio API key and User ID
  • How to create a Composio Tool Router session for Spotify
  • How to attach an MCP Server to a Pydantic AI agent
  • How to stream responses and maintain chat history
  • How to build a simple REPL-style chat interface to test your Spotify workflows

What is Pydantic AI?

Pydantic AI is a Python framework for building AI agents with strong typing and validation. It leverages Pydantic's data validation capabilities to create robust, type-safe AI applications.

Key features include:

  • Type Safety: Built on Pydantic for automatic data validation
  • MCP Support: Native support for Model Context Protocol servers
  • Streaming: Built-in support for streaming responses
  • Async First: Designed for async/await patterns

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 starting, make sure you have:
  • Python 3.9 or higher
  • A Composio account with an active API key
  • Basic familiarity with Python and async programming
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 dependencies

bash
pip install composio pydantic-ai python-dotenv

Install the required libraries.

What's happening:

  • composio connects your agent to external SaaS tools like Spotify
  • pydantic-ai lets you create structured AI agents with tool support
  • python-dotenv loads your environment variables securely from a .env file
4

Set up environment variables

bash
COMPOSIO_API_KEY=your_composio_api_key_here
USER_ID=your_user_id_here
OPENAI_API_KEY=your_openai_api_key

Create a .env file in your project root.

What's happening:

  • COMPOSIO_API_KEY authenticates your agent to Composio's API
  • USER_ID associates your session with your account for secure tool access
  • OPENAI_API_KEY to access OpenAI LLMs
5

Import dependencies

python
import asyncio
import os
from dotenv import load_dotenv
from composio import Composio
from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStreamableHTTP

load_dotenv()
What's happening:
  • We load environment variables and import required modules
  • Composio manages connections to Spotify
  • MCPServerStreamableHTTP connects to the Spotify MCP server endpoint
  • Agent from Pydantic AI lets you define and run the AI assistant
6

Create a Tool Router Session

python
async def main():
    api_key = os.getenv("COMPOSIO_API_KEY")
    user_id = os.getenv("USER_ID")
    if not api_key or not user_id:
        raise RuntimeError("Set COMPOSIO_API_KEY and USER_ID in your environment")

    # Create a Composio Tool Router session for Spotify
    composio = Composio(api_key=api_key)
    session = composio.create(
        user_id=user_id,
        toolkits=["spotify"],
    )
    url = session.mcp.url
    if not url:
        raise ValueError("Composio session did not return an 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 session.mcp.url is the MCP server URL that your agent will use
7

Initialize the Pydantic AI Agent

python
# Attach the MCP server to a Pydantic AI Agent
spotify_mcp = MCPServerStreamableHTTP(url, headers={"x-api-key": COMPOSIO_API_KEY})
agent = Agent(
    "openai:gpt-5",
    toolsets=[spotify_mcp],
    instructions=(
        "You are a Spotify assistant. Use Spotify tools to help users "
        "with their requests. Ask clarifying questions when needed."
    ),
)
What's happening:
  • The MCP client connects to the Spotify endpoint
  • The agent uses GPT-5 to interpret user commands and perform Spotify operations
  • The instructions field defines the agent's role and behavior
8

Build the chat interface

python
# Simple REPL with message history
history = []
print("Chat started! Type 'exit' or 'quit' to end.\n")
print("Try asking the agent to help you with Spotify.\n")

while True:
    user_input = input("You: ").strip()
    if user_input.lower() in {"exit", "quit", "bye"}:
        print("\nGoodbye!")
        break
    if not user_input:
        continue

    print("\nAgent is thinking...\n", flush=True)

    async with agent.run_stream(user_input, message_history=history) as stream_result:
        collected_text = ""
        async for chunk in stream_result.stream_output():
            text_piece = None
            if isinstance(chunk, str):
                text_piece = chunk
            elif hasattr(chunk, "delta") and isinstance(chunk.delta, str):
                text_piece = chunk.delta
            elif hasattr(chunk, "text"):
                text_piece = chunk.text
            if text_piece:
                collected_text += text_piece
        result = stream_result

    print(f"Agent: {collected_text}\n")
    history = result.all_messages()
What's happening:
  • The agent reads input from the terminal and streams its response
  • Spotify API calls happen automatically under the hood
  • The model keeps conversation history to maintain context across turns
9

Run the application

python
if __name__ == "__main__":
    asyncio.run(main())
What's happening:
  • The asyncio loop launches the agent and keeps it running until you exit

Complete Code

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

python
import asyncio
import os
from dotenv import load_dotenv
from composio import Composio
from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStreamableHTTP

load_dotenv()

async def main():
    api_key = os.getenv("COMPOSIO_API_KEY")
    user_id = os.getenv("USER_ID")
    if not api_key or not user_id:
        raise RuntimeError("Set COMPOSIO_API_KEY and USER_ID in your environment")

    # Create a Composio Tool Router session for Spotify
    composio = Composio(api_key=api_key)
    session = composio.create(
        user_id=user_id,
        toolkits=["spotify"],
    )
    url = session.mcp.url
    if not url:
        raise ValueError("Composio session did not return an MCP URL")

    # Attach the MCP server to a Pydantic AI Agent
    spotify_mcp = MCPServerStreamableHTTP(url, headers={"x-api-key": COMPOSIO_API_KEY})
    agent = Agent(
        "openai:gpt-5",
        toolsets=[spotify_mcp],
        instructions=(
            "You are a Spotify assistant. Use Spotify tools to help users "
            "with their requests. Ask clarifying questions when needed."
        ),
    )

    # Simple REPL with message history
    history = []
    print("Chat started! Type 'exit' or 'quit' to end.\n")
    print("Try asking the agent to help you with Spotify.\n")

    while True:
        user_input = input("You: ").strip()
        if user_input.lower() in {"exit", "quit", "bye"}:
            print("\nGoodbye!")
            break
        if not user_input:
            continue

        print("\nAgent is thinking...\n", flush=True)

        async with agent.run_stream(user_input, message_history=history) as stream_result:
            collected_text = ""
            async for chunk in stream_result.stream_output():
                text_piece = None
                if isinstance(chunk, str):
                    text_piece = chunk
                elif hasattr(chunk, "delta") and isinstance(chunk.delta, str):
                    text_piece = chunk.delta
                elif hasattr(chunk, "text"):
                    text_piece = chunk.text
                if text_piece:
                    collected_text += text_piece
            result = stream_result

        print(f"Agent: {collected_text}\n")
        history = result.all_messages()

if __name__ == "__main__":
    asyncio.run(main())

Conclusion

You've built a Pydantic AI agent that can interact with Spotify through Composio's Tool Router. With this setup, your agent can perform real Spotify actions through natural language. You can extend this further by:
  • Adding other toolkits like Gmail, HubSpot, or Salesforce
  • Building a web-based chat interface around this agent
  • Using multiple MCP endpoints to enable cross-app workflows (for example, Gmail + Spotify for workflow automation)
This architecture makes your AI agent "agent-native", able to securely use APIs in a unified, composable way without custom integrations.
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