# Patchline MCP — Install + Tool list

> Install the Patchline MCP server in your AI client. 46 tools
> spanning your entire music business workflow.

## Endpoint

`https://www.patchline.ai/api/mcp/v1`

## Auth

OAuth 2.0 with PKCE. The endpoint returns 401 with a `WWW-Authenticate`
header pointing at `https://www.patchline.ai/.well-known/oauth-protected-resource`.

## Install

### Cursor

```json
{
  "mcpServers": {
    "aria": { "url": "https://www.patchline.ai/api/mcp/v1" }
  }
}
```

One-click: `cursor://anysphere.cursor-deeplink/mcp/install?name=aria&config=eyJhcmlhIjp7InVybCI6Imh0dHBzOi8vd3d3LnBhdGNobGluZS5haS9hcGkvbWNwL3YxIn19`

### Codex

```bash
codex mcp add aria --url https://www.patchline.ai/api/mcp/v1
```

Requires `experimental_use_rmcp_client = true` in `~/.codex/config.toml`.

### VS Code

```json
{
  "mcpServers": {
    "aria": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://www.patchline.ai/api/mcp/v1"]
    }
  }
}
```

### Claude Desktop

```json
{
  "mcpServers": {
    "aria": { "url": "https://www.patchline.ai/api/mcp/v1", "transport": "http" }
  }
}
```

## Tool list

- `analyze_url` _(Dispatch)_ — Universal dispatcher for Spotify URLs (track, artist, album, playlist) and YouTube URLs (video, channel). Paste a link and get the canonical identity plus a ranked list of next MCP tools to call with exact arguments. Call this FIRST whenever a user shares a Spotify or YouTube link; for artist profiles on other platforms, pass the profile URL straight to add_artist.
- `browse_catalog` _(Catalog)_ — List tracks in the user catalog with pagination — title, ISRC, BPM, key, status. Optional artistId scopes to one roster artist (manager accounts).
- `import_track_from_url` _(Catalog)_ — Import a track's metadata into the catalog from a Spotify track URL — creates a catalog entry with title, artist, ISRC, and platform link (no audio; pair with get_asset_upload_link for audio). Resolve title/artist/ISRC via get_song_intelligence first. Dedup-safe on re-import.
- `get_audience_overview` _(Audience)_ — Aggregate fan-graph overview: total fans, captures (7/30d), repeat and active fans, buyers, store revenue, capture rate, and identity stats. Aggregates only — no fan names or emails.
- `get_audience_geo` _(Audience)_ — City-level fan geography: hubs with fan counts, total countries/cities, configurable lookback window. For tour routing and geo-targeted promotion. Aggregates only.
- `catalog_search` _(Catalog)_ — Search across the user catalog by title, artist, ISRC, and metadata. Defaults to music/audio assets; set includeNonAudio only when the user asks for cover art, images, or documents.
- `get_asset` _(Catalog)_ — Full metadata for a single track by asset ID — covers, audio features, version history, distribution status.
- `get_artist_intelligence` _(Artists)_ — Cached roster intelligence for a single artist: streaming, social audience, genres, recent activity. Run add_artist first if the artist is missing.
- `search_artists` _(Artists)_ — Search artists by name within the user roster.
- `get_trending_artists` _(Artists)_ — Top artists by streaming reach. Optional genre filter accepts user labels like Electronic/Dance and normalizes to Patchline internal tags. Not market-specific.
- `refresh_artist_intelligence` _(Artists)_ — Queue a refresh for one roster artist through Patchline’s existing EventBridge artist enrichment pipeline. Stale-only by default; does not call the enrichment Lambda directly.
- `refresh_roster_intelligence` _(Artists)_ — Queue bounded stale-only intelligence refreshes for up to 10 roster artists through Patchline’s existing EventBridge enrichment pipeline. Returns queued/skipped/failed counts.
- `add_artist` _(Roster)_ — Add an artist to the user roster. REQUIRES a platform URL (Spotify, YouTube, TikTok, SoundCloud, Apple Music, or Instagram). Name-only is rejected because many artists share names. Triggers background audience enrichment.
- `remove_artist` _(Roster)_ — Remove an artist from the user roster by patchlineArtistId.
- `browse_roster` _(Roster)_ — List or filter the authenticated user roster — artists with IDs, platform IDs, enrichment status, genres, and metrics. No query required.
- `get_releases` _(Releases)_ — Release plans, schedules, and campaign details for the authenticated user.
- `find_playlists` _(Playlists)_ — Playlist match opportunities ranked by sonic fit and curator responsiveness for a given track.
- `inspect_playlist` _(Playlists)_ — Full Spotify playlist intelligence: curator identity, genres, freshness, followers, track turnover, recent additions, submission status.
- `create_smart_link` _(Smart Links)_ — Smart link landing page for an owned catalog track — server-side resolves ISRC, DSP URLs, and cover art. For pre-release campaigns use create_drop_link instead.
- `list_store_listings` _(Storefront)_ — List authenticated-user store inventory and listing readiness. Read-only; reports seller agreement, payout, rights, AI-policy, audio, and marketplace blockers inherited from the store route.
- `manage_store_listing` _(Storefront)_ — Validate, list, unlist, price, reorder, or update metadata for store inventory by wrapping the existing store inventory route. Mutations inherit all commerce safety checks.
- `create_store_link` _(Storefront)_ — Create or return the authenticated user’s public store surface by wrapping the existing store share route. Returns a store share URL and normalized section config.
- `get_store_analytics` _(Storefront)_ — Read aggregate store analytics: views, revenue, orders, conversion, and recent sales with buyer emails redacted from MCP output.
- `get_fan_segments` _(Storefront)_ — Read aggregate store fan segments and engagement stats for the user-owned store surface. No raw fan emails, names, or per-fan journeys.
- `create_drop_link` _(Smart Links)_ — Create a public release/drop link for an owned release. Returns the share URL plus normalized section config.
- `create_pitch_link` _(Smart Links)_ — Create a public curator pitch link for an owned track, optionally attaching a secure asset handoff.
- `create_asset_share` _(Smart Links)_ — Create a public asset share link for an owned catalog asset without changing the asset itself. Returns a share URL and normalized section config.
- `create_media_kit` _(Smart Links)_ — Create a public artist media-kit page for an owned roster artist. Supports page or PDF output.
- `create_briefing` _(Smart Links)_ — Create a public briefing/report microsite from markdown, validated structured modules, and optional Patchline source references. Template-driven only; does not create arbitrary HTML/CSS/JS.
- `list_share_surfaces` _(Smart Links)_ — List owner-safe public surfaces for the authenticated user, including briefing/report microsites, smart links, drops, pitch links, asset shares, media kits, and stores.
- `get_share_surface` _(Smart Links)_ — Read owner-safe metadata, normalized section config, source refs, and analytics for a public share surface by URL or shareId.
- `manage_share_surface` _(Smart Links)_ — Update briefing/report microsite metadata or revoke a public share surface. Revoke unpublishes the surface and is destructive.
- `get_surface_analytics` _(Smart Links)_ — Read aggregate analytics for an owned public share surface: views, captures, downloads, plays, last viewed, and linked asset/project/campaign IDs.
- `read_public_surface` _(Smart Links)_ — Read owner-safe metadata and section config for a public surface (drop, pitch, asset, media-kit, briefing, smart link, or store) by URL or shareId.
- `get_audio_features` _(Music Data)_ — BPM, key, mood, danceability, and genre tags for a track. Accepts assetId or ISRC.
- `get_song_intelligence` _(Music Data)_ — Full track intelligence: ISRC, audio analysis, playlist matches, streaming stats, collaborators. Accepts a Spotify track URL.
- `get_work_metadata` _(Music Data)_ — Writers, publishers, and ISWC for a musical work. Requires Spotify track ID/URL or ISRC; song title alone returns an identifier-needed envelope.
- `find_similar_tracks` _(Music Data)_ — Find tracks with similar audio characteristics (vibe, instrumentation, production) to a given catalog asset, ranked by audio-embedding similarity. Restricted to the caller-owned catalog.
- `get_bio` _(AI Generation)_ — Returns the AI-generated bio for an artist from intelligence cache. Populated during enrichment — no live LLM call.
- `generate_pitch` _(AI Generation)_ — Playlist curator pitch for a specific track. Standard mode is grounded in real track/audio/audience data; cold_start requires verified_context and returns INSUFFICIENT_DATA instead of ungrounded or template copy.
- `get_asset_upload_link` _(Asset Upload)_ — Create a new Asset Hub record and return a short-lived presigned S3 URL so the client can PUT audio bytes directly to storage. Audio bytes do NOT pass through the MCP server. After the upload completes, call confirm_asset_upload.
- `create_upload_link` _(Asset Upload)_ — Create a short-lived secure browser upload link for a human handoff when the MCP client cannot upload bytes directly. The user opens the link while signed in to Patchline; this does not upload bytes or bypass user auth.
- `confirm_asset_upload` _(Asset Upload)_ — Confirm a direct-to-S3 audio upload created by get_asset_upload_link. Marks the asset ready and triggers Patchline track analysis (audio fingerprinting, aiMetadata extraction).
- `create_project` _(Projects)_ — Create a real Patchline Project Anchor for the signed-in user. Use during Aria start after artist resolution so the local workspace is linked to the Patchline dashboard. Requires artistId from add_artist.
- `get_artist_context` _(Projects)_ — Best-effort read of safe artist/account campaign context for Aria planning: connected platforms, distributor preference, email-list bucket, Telegram linkage, recent releases, defaults. Unknown fields return null instead of failing.
- `create_campaign` _(Projects)_ — Generate and persist a Patchline Project campaign/action list. Use after release-plan inputs are known so dashboard campaign tasks are created, not just written to local markdown. Requires projectId from create_project.

## Example prompts

- "Start Aria for this artist: https://open.spotify.com/artist/..."
- "Summarize my streaming momentum in the last month."
- "Find playlist opportunities for my new upcoming track."
- "Generate a smart link for my latest track."

## Rules

See https://www.patchline.ai/AGENTS.md for the prescriptive ALWAYS / NEVER /
DISCOURAGED rules.