MCP tools reference

Human-readable reference for Patchline’s stable public MCP tools. This page documents the full public surface (49 tools as of this writing). For the exact current schema, connect an MCP client to https://www.patchline.ai/api/mcp/v1 and run tools/list — that MCP response is the machine-readable source of truth. All tools are accessible on every tier; some are gated by tier limits (see per-tool notes).

Onboarding

Start here when you don’t know where to begin. get_started reads the workspace and names the single best next action. Arguments: none. Returns the workspace summary (artists, tracks, releases) plus a ranked nextActions list with example tool calls.

Dispatch

The most-important tool. Always call this first when a user pastes a streaming URL. Arguments: url: string (required) — a Spotify (track, artist, album, playlist) or YouTube (video, channel) URL. Returns: Canonical identity (type, id, name, platform) plus a ranked list of nextSteps — exact tool names with exact argument values. Example call:

{
  "name": "analyze_url",
  "arguments": {
    "url": "https://open.spotify.com/track/4iV5W9uYEdYUVa79Axb7Rh"
  }
}

Example return:

{
  "type": "track",
  "id": "4iV5W9uYEdYUVa79Axb7Rh",
  "isrc": "GBUM71029604",
  "name": "Bohemian Rhapsody",
  "artist": "Queen",
  "platform": "spotify",
  "nextSteps": [
    { "tool": "get_song_intelligence", "args": { "spotify_url": "..." } },
    { "tool": "get_audio_features",     "args": { "isrc": "GBUM71029604" } }
  ]
}

Catalog

Common arguments: page: int (default 1), pageSize: int (default 20, max 50), artistId: string (optional roster scope), includeNonAudio: bool. Arguments: query: string (free text), limit: int (default 10), includeNonAudio: bool. Common arguments: assetId: string (the Patchline asset ID), mode: "summary" | "full". Common arguments: a Spotify track URL. Resolve title/artist/ISRC with get_song_intelligence first. Pass allowLowConfidenceArtist:true only after confirming the artist with the user. Common arguments: an action (duplicate-candidate scan, archive/restore, reattribution preview, canonical-recording repair, or set_cover_art) plus the relevant asset IDs and a confirmation token for applied repairs.

Audience

Aggregate fan analytics only. These tools never return fan names or emails. Common arguments: lookbackDays: int (optional window).

Artists & roster

Common arguments: artist_name: string (required), mode: "summary" | "full". Arguments: query: string (artist name fragment). Common arguments: genre: string (optional), market: string (ISO2), min_monthly_listeners: int, max_monthly_listeners: int, limit: int. Common arguments: artistId: string. Stale-only by default. Common arguments: none required. Refreshes up to 10 stale roster artists. Common arguments: artist_url: string (Spotify, YouTube, TikTok, SoundCloud, Apple Music, or Instagram) or an ariaArtistId from search_artists / get_trending_artists, plus an optional artist_name display hint. Gated by: roster tier limit (Free 1 / Starter 1 / Pro 5 / Scale 20 / Enterprise unlimited). Common arguments: patchlineArtistId: string. Arguments: none required; optional filters by enrichment status or genre. Arguments: none. Read-only weekly brief.

Releases

Arguments: status: string (optional — in_progress / scheduled / released / archived), limit: int (default 10).

Playlists

Common arguments: assetId: string (preferred catalog track), spotifyUrl: string (optional), limit: int. Gated by: required. Common arguments: playlist_url: string (Spotify playlist ID or URL), include_tracks: bool, include_curator_network: bool. Gated by: required.

Smart links & public surfaces

Public share surfaces for owned catalog and releases. Creating one returns a shareUrl; reads and analytics are owner-safe. Common arguments: assetId: string, title: string (optional), enabledSections (optional section toggles). Common arguments: releaseId: string, optional pre-save / store CTA URLs and enabledSections. Common arguments: assetId: string, optional enabledSections. Common arguments: markdown body plus validated structured modules and optional Patchline source references. Common arguments: surfaceType: "drop" | "smartlink" | "asset" | "briefing" | "store" (optional), limit: int. Common arguments: url: string or shareId: string. Common arguments: shareId: string plus an update or revoke action. Revoke is destructive (unpublishes the surface). Common arguments: url: string or shareId: string. Common arguments: url: string or shareId: string.

Storefront

Arguments: none required. Read-only readiness + blockers. Common arguments: an action (validate / list / unlist / price / reorder / update) plus the listing identifiers. Common arguments: projectId: string (optional), enabledSections (optional). Arguments: none required. Buyer emails are redacted from MCP output. Arguments: none required. Aggregates only.

Music Data

Common arguments: assetId: string (preferred), isrc: string, or spotifyTrackUrl: string. Common arguments: assetId: string, isrc: string, or spotifyTrackUrl: string; optional mode: "summary" | "full". Common arguments: spotifyId, spotifyTrackUrl, or isrc. Common arguments: assetId: string (a catalog track), limit: int.

AI Generation

Common arguments: artist_name: string. Note: Returns cached bio from intelligence enrichment. No live LLM call. Free. Common arguments: artist_name: string, track_name: string (optional), assetId: string (optional, preferred for grounding), target_playlist: string (optional). Common arguments: a prompt describing the cover art or flyer. Only call when the user explicitly asks for generated artwork; prefer uploads when they already have assets.

Asset Upload

Bytes never pass through the MCP server. The client uploads directly to a presigned S3 URL, then confirms. Common arguments: fileName: string (extension decides audio vs image). Returns a presigned uploadUrl + assetId; PUT bytes to it, then call confirm_asset_upload. Common arguments: none required. Returns a secure browser upload link for a human handoff. Common arguments: assetId: string (from get_asset_upload_link).

Projects

The Patchline project + campaign planning loop. Used during an Aria session to link the workspace to the dashboard. Common arguments: artistId: string (from add_artist). Common arguments: artistId: string. Unknown fields return null instead of failing. Common arguments: projectId: string (from create_project). Returns polling guidance. Common arguments: projectId: string. Poll with a bounded retry loop until completed or failed.

Common patterns

”User pasted a URL — what do I do?”

Always:

Call analyze_url with the URL.
Read the returned nextSteps.
Call those tools with the exact arguments provided.

This pattern saves 2-3 round-trips vs. trying to guess what the URL is.

”I don’t know where to start”

Call get_started. It reports the workspace and the single best next action, so you don’t have to probe with multiple reads.

”User wants to add an artist by name”

Reject name-only. The MCP tool reflects this:

"add_artist" requires a `url` argument — a Spotify, YouTube, TikTok,
SoundCloud, Apple Music, or Instagram URL. Name-only is rejected
because many artists share names.

Use search_artists to find a candidate URL or ariaArtistId, then add_artist.

”User asks about a track that’s not in their catalog”

Two options:

Use analyze_url if they shared a URL — gets you the metadata without importing.
import_track_from_url to bring the metadata into the catalog, or recommend they import or upload the master. Once imported, all catalog tools work on it.

Rate limits

In practice, you’ll hit AI-credit limits before MCP rate limits. The server enforces sane per-user limits to prevent abuse but doesn’t publish hard rate-limit numbers.

Source of truth

This page is the human-readable guide for stable public behavior.
The MCP server’s tools/list response is the exact current machine-readable schema and tool count.
Client implementations should avoid caching schemas permanently.

MCP overview — what MCP is, two-server explainer
MCP install — per-client install
AGENTS.md explained — rules of engagement
Aria overview — same tools, conversation form

​Onboarding

​Dispatch

​Catalog

​Audience

​Artists & roster

​Releases

​Playlists

​Smart links & public surfaces

​Storefront

​Music Data

​AI Generation

​Asset Upload

​Projects

​Common patterns

​”User pasted a URL — what do I do?”

​”I don’t know where to start”

​”User wants to add an artist by name”

​”User asks about a track that’s not in their catalog”

​Rate limits

​Source of truth

​Related pages