Tag-per-Track

Tag-per-Track MCP Server

This project is a local Model Context Protocol (MCP) server that allows AI agents (like Claude) to analyze audio files via the Tag-per-Track API. It authenticates either with a Studio API key (prepaid credits bought on tag-per-track.cloud, no crypto needed) or with a wallet, in which case it automatically handles the USDC micro-payment using the x402 protocol on the Base network.

🎯 Vision

Enable an AI to "pay to listen" autonomously. When an AI agent wants to analyze a track, it uses this MCP server, which signs an EIP-3009 (USDC) payment authorization and instantly retrieves the enriched track metadata.

🚀 Features

• `analyze_audio` Tool (Canonical): Extracts BPM, Genre, Mood, Key, Instruments, production metrics, optional Lyrics (1 credit or 0.15 USDC standard / 2 credits or 0.25 USDC with lyrics), AI-Generated Music Detection (ai_detection: Suno, Udio, neural vocoders with HUMAN, AI_GENERATED, or UNCERTAIN verdicts) and the server-side A&R evaluation (arEvaluation: discovery / signing / beatmaker profiles).
• `analyze_audio_with_lyrics` Tool (Alias): Extracts complete musical metadata, transcribes full vocal lyrics, and returns AI origin integrity metrics (2 credits or 0.25 USDC).
• `analyze_audio_batch` Tool (Parallel Processing): Analyzes multiple music tracks concurrently with AI origin detection on every track, dramatically reducing turnaround time for albums and playlists.
• `triage_demo_folder` Tool (Demo Inbox Triage): Sorts a whole local folder of demos in one call: analysis, artist/title from Artist - Title file names or audio tags, Spotify traction, A&R scoring v2 re-computed with the traction, and a compact ranked report with buckets (priority, listen, pass, ai_flagged, error). Unreliable lyrics (instrumental, no voice, looping hallucination) are flagged instead of quoted.
• `lookup_artist_stats` Tool (A&R Traction): Fetches public Spotify streaming traction (monthly listeners, followers, popularity score, genres) for hybrid A&R qualification.
• Selective Audio Compression: Automatically compresses heavy uncompressed files (.wav, .aiff, .aif) or audio files larger than 15 MB to 128 kbps AAC (.m4a) before upload (using native macOS afconvert or ffmpeg), reducing upload bandwidth and latency by up to 90% while leaving lightweight files (.mp3, .m4a $\le 15$ MB) untouched.
• Prices in the Right Unit: tool descriptions, prompts and reports state costs in studio credits when a Studio API key is configured, and in USDC only in wallet (x402) mode, so an A&R paying with credits never sees crypto amounts.
• Dual Authentication: Studio API key (Authorization: Bearer tpt_live_…, prepaid credits) takes priority over the Web3 wallet.
• Automated x402 Payment: Manages the x402 challenge-response cycle (HTTP 402), with the platform wallet and USDC contracts pinned client-side.
• Integrated Web3: On-chain signing via viem (EIP-3009 TransferWithAuthorization on Base).
• Client-Side Financial Guard (Spending Cap): Built-in spending limit (default 0.50 USDC max per call) protecting your wallet against abnormal requests.
• Confidential by Default for x402: Wallet-paid analyses are sent with x-no-persist (not stored server-side); Studio API key analyses are saved to your dashboard history unless TAG_PER_TRACK_NO_PERSIST=1.
• Prompts: triage_demos (sort a demo folder into a ranked shortlist and sub-folders), qualify_demo_ar (single demo A&R qualification) and batch_demo_screening (multi-track screening).
• Strict File Format Validation: Rejects non-audio files to protect local privacy and prevent arbitrary file exfiltration.
• Deferred Binary Loading & Timeouts: 15s handshake / 120s processing timeouts with memory-efficient streaming and automatic temp file cleanup.
• Compatibility: Designed for use with Claude Desktop, Cursor, Windsurf, or any MCP client.

⚙️ Configuration & Environment Variables

The MCP server supports Dual Authentication:

📦 Installation & Setup

🤖 Option 1: Claude Desktop (Studio SaaS - Zero Crypto, Recommended for A&R)

Add the server to your claude_desktop_config.json (located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{

"mcpServers": { "tag-per-track": { "command": "npx", "args": [ "-y", "tag-per-track-mcp@latest" ], "env": { "TAG_PER_TRACK_API_KEY": "tpt_live_YOUR_STUDIO_API_KEY_HERE" } } } }

*Note: Generate your Studio API key in 1 click from your Dashboard at [https://tag-per-track.cloud](https://tag-per-track.cloud).*

⚡ Option 2: Claude Desktop (Web3 x402 USDC on Base)

{

"mcpServers": { "tag-per-track": { "command": "npx", "args": [ "-y", "tag-per-track-mcp@latest" ], "env": { "WALLET_PRIVATE_KEY": "0xYOUR_BURNER_WALLET_PRIVATE_KEY_HERE", "MAX_SPENDING_USDC": "0.50" } } } }

🌐 Option 3: Smithery CLI

# For Claude Desktop

npx -y @smithery/cli@latest mcp add lori-ferrand/tag-per-track --client claude

For Cursor

npx -y @smithery/cli@latest mcp add lori-ferrand/tag-per-track --client cursor

The server is also listed on the official MCP registry as io.github.Lory97/tag-per-track-mcp.

🔧 MCP Tools

1. analyze_audio

Analyzes an audio file to extract musical metadata tags (BPM, key, scale, moods, genres, instruments), optional lyrics, and AI Origin Integrity (ai_detection). Supports both local binary files and remote URLs.

• Arguments:
• filePath (*string*, optional): Path to a local audio file on disk (.mp3, .wav, .ogg, .flac, .m4a, .aac, .aiff). The server validates the format, reads the file and streams it securely.
• fileUrl (*string*, optional): Direct URL of the audio file. *(Note: At least one of filePath or fileUrl must be provided).*
• extractLyrics (*boolean*, optional): Set to true to also extract vocal lyrics (2 credits / 0.25 USDC instead of 1 credit / 0.15 USDC).

• Output Structure: Returns comprehensive metadata including:
• bpm, key, scale, genres, moods, instruments, duration
• production (lufs, peakDb, clippedRatio), danceability, engagement, approachability, voice.ratio
• ai_detection / aiDetection (computed on a 12 s core sample):
• checked: boolean (true when analyzed)
• isAi: boolean (true if detected as synthetic/AI)
• confidence: confidence percentage (0-100)
• verdict: 'HUMAN' | 'AI_GENERATED' | 'UNCERTAIN'
• status: 'SUCCESS' | 'UNAVAILABLE' | 'SKIPPED'
• generator / watermarkDetected (optional): identified generator, e.g. a Suno signature in the file metadata
• arEvaluation (A&R scoring v2.2): tier, audioType, suggestedProfile, marketplaceTags, aiGate, subScores (production, listening, traction, loyalty) and profiles.{discovery,signing,beatmaker} with score, priority and a recommendation code. AI verdicts are graded: ≥ 70 % confidence (or a metadata watermark) blocks the track, 60-69 % flags it, 30-59 % is inconclusive.
• lyricsInfo (with extractLyrics): language detected by Whisper, reliability (high, approximate, none) and avgLogprob.

2. analyze_audio_with_lyrics

Analyzes an audio file to extract musical metadata, transcribe full vocal lyrics using AI, and evaluate AI Origin Integrity. Supports local audio files and remote URLs.

• Arguments:
• filePath (*string*, optional): Path to a local audio file on disk (.mp3, .wav, .ogg, .flac, .m4a, .aac, .aiff).
• fileUrl (*string*, optional): Direct URL of the audio file. *(Note: At least one of filePath or fileUrl must be provided).*

3. analyze_audio_batch

Analyzes multiple audio tracks in parallel (batch processing). Vastly reduces total execution time compared to sequential calls, with resilient partial reporting and AI origin detection on every track.

• Arguments:
• filePaths (*string[]*, optional): Convenience array of local file paths to analyze in parallel.
• fileUrls (*string[]*, optional): Convenience array of public URLs to analyze in parallel.
• tracks (*object[]*, optional): Array of track objects with granular settings:
• filePath (*string*, optional)
• fileUrl (*string*, optional)
• extractLyrics (*boolean*, optional): Per-track lyrics flag.
• extractLyrics (*boolean*, optional): Global flag to transcribe vocal lyrics for all tracks in this batch (2 credits / 0.25 USDC per track). Default is false (1 credit / 0.15 USDC per track).
• concurrency (*number*, optional): Maximum simultaneous parallel requests (1 to 5, default is 4 to respect API rate limits).

• Output Structure: Returns a summary JSON containing:
• totalTracks: Total number of tracks submitted.
• successful: Count of successfully analyzed tracks.
• failed: Count of failed tracks.
• results: Detailed array containing status (success or error), metadata (including ai_detection), or error reason for each track.

4. triage_demo_folder

Sorts a local folder of demo submissions in one call, built for the A&R "demo inbox" workflow. Only compact results are returned, so a 20-track folder fits comfortably in the model context.

Pipeline: list the audio files → artist/title from an Artist - Title file name (preferred: tags on demos are often DAW or account defaults), else from the audio tags → paid analyses (bounded concurrency) → one free Spotify lookup per distinct main artist ("Miimii ft Dj Skycee" → "Miimii") → free server-side re-scoring (POST /api/ar-score) with the traction attached → ranking. MCP progress notifications are sent after each track when the client provides a progressToken.

• Arguments:
• folderPath (*string*, required): Local folder (absolute or ~/...).
• profile (*string*, optional): discovery (default, an unknown artist is never penalized), signing (weighs streaming traction), beatmaker, or auto (beatmaker for instrumentals).
• extractLyrics (*boolean*, optional): Also transcribe lyrics (2 credits / 0.25 USDC per tra