MCP_instructions.md

---
title: Demo MIT - MCP Server
emoji: 💻
colorFrom: green
colorTo: gray
sdk: gradio
sdk_version: 5.29.0
app_file: app.py
pinned: false
---
---

# Spotify MCP Server

Spotify MCP (Model Context Protocol) server, implemented with **FastAPI + FastMCP**.
It authenticates a Spotify account via OAuth2 and exposes MCP tools to query profile data, search tracks, read library/recent playback, and manage playlists.

## Target Deployment (Hugging Face)

This server runs in the Space:

- `pharmaia/Demo_MCP_Server_Spotify`
- https://huggingface.co/spaces/pharmaia/Demo_MCP_Server_Spotify

Public base URL:

- `https://pharmaia-demo-mcp-server-spotify.hf.space`

Public MCP SSE endpoint:

- `https://pharmaia-demo-mcp-server-spotify.hf.space/gradio_api/mcp/sse`

## General Architecture

- `FastAPI` exposes HTTP endpoints for healthcheck and OAuth flow.
- `FastMCP` registers MCP tools and publishes them over SSE.
- `httpx` performs calls to Spotify Accounts API (tokens) and Spotify Web API (data/actions).
- `spotify_tokens.json` (or a configurable path) stores tokens and expiration metadata.

## Authentication Flow

1. The client opens `/auth/login`.
2. The server generates an anti-CSRF `state` and redirects to Spotify `/authorize`.
3. Spotify redirects to `/auth/callback` with `code` + `state`.
4. The server validates `state`, exchanges `code` for tokens, and saves them.
5. MCP tools use the stored token; if expired, the server attempts automatic refresh.

## HTTP Endpoints (Production)

- `GET /`: basic service metadata and useful routes.
- `GET /health`: simple status (`ok`).
- `GET /auth/status`: local token status.
- `GET /auth/reset`: removes local token (forces re-authentication).
- `GET /auth/login?force=true`: starts OAuth (with consent dialog).
- `GET /auth/callback`: Spotify OAuth callback.
- `SSE /gradio_api/mcp/sse`: MCP SSE transport (mounted by FastMCP).

## Main MCP Tools

- `spotify_auth_status`: authentication status.
- `spotify_get_auth_url`: direct OAuth authorization URL.
- `spotify_get_my_profile`: current user profile.
- `spotify_search_tracks`: track search.
- `spotify_list_saved_tracks`: saved tracks.
- `spotify_list_recently_played`: recently played tracks.
- `spotify_get_top_tracks`: top tracks by time range.
- `spotify_check_saved_tracks`: checks whether tracks are saved.
- `spotify_save_tracks` / `spotify_remove_saved_tracks` / `spotify_set_tracks_saved`.
- `spotify_list_my_playlists`: user playlists.
- `spotify_create_playlist`: create playlist.
- `spotify_add_items_to_playlist`: add items.
- `spotify_update_playlist_details`: update metadata.
- `spotify_replace_playlist_items`: replace content.
- `spotify_delete_playlist`: delete (unfollow) playlist.

## Environment Variables (Hugging Face Spaces)

Configure in **Space Settings > Variables and secrets**:

- `SPOTIFY_CLIENT_ID`
- `SPOTIFY_CLIENT_SECRET`
- `SPOTIFY_REDIRECT_URI` = `https://pharmaia-demo-mcp-server-spotify.hf.space/auth/callback`
- `SPOTIFY_SCOPES` (optional; the server appends required scopes)
- `SPOTIFY_TOKEN_FILE` (optional; default `spotify_tokens.json`)
- `MCP_PUBLIC_SSE_URL` = `https://pharmaia-demo-mcp-server-spotify.hf.space/gradio_api/mcp/sse`
- `PORT` (optional; default `7860`)

Important: in Spotify Developer Dashboard, the Redirect URI must match exactly:

- `https://pharmaia-demo-mcp-server-spotify.hf.space/auth/callback`

## Production Usage (HF Space)

1. Open OAuth login:

- `https://pharmaia-demo-mcp-server-spotify.hf.space/auth/login`

2. Complete Spotify consent.
3. Check status:

- `https://pharmaia-demo-mcp-server-spotify.hf.space/auth/status`

4. Connect MCP client to the public SSE endpoint:

- `https://pharmaia-demo-mcp-server-spotify.hf.space/gradio_api/mcp/sse`

## Local Run (Optional)

1. Install dependencies:

```bash
pip install -r requirements.txt
```

2. Start the server:

```bash
python app.py
```

3. Open in browser:

- `http://localhost:7860/auth/login`

4. Connect MCP client to local SSE endpoint:

- `http://localhost:7860/gradio_api/mcp/sse`

## Design Notes

- The server keeps OAuth state in memory with TTL to prevent callback replay.
- Scopes are validated for sensitive playlist operations.
- Spotify IDs/URIs/URLs are normalized before API calls.
- Spotify responses are transformed into compact payloads for MCP tool consumption.