> ## Documentation Index
> Fetch the complete documentation index at: https://docs.patchline.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP tools reference

> Human-readable reference for Patchline's stable public MCP tool families — behavior, common arguments, tier gating, and examples. Use MCP tools/list for the exact current schema.

export const MCPToolCard = ({name}) => {
  const t = MCP_TOOLS[name];
  if (!t) {
    return <div style={{
      padding: "12px",
      border: "1px dashed #f87171",
      borderRadius: "8px"
    }}>
        Unknown MCP tool: <code>{name}</code>
      </div>;
  }
  const badges = {
    Onboarding: "#00E6E2",
    Dispatch: "#818CF8",
    Catalog: "#22D3EE",
    Audience: "#2DD4BF",
    Artists: "#60A5FA",
    Roster: "#60A5FA",
    Releases: "#C084FC",
    Playlists: "#4ADE80",
    "Smart Links": "#FACC15",
    Storefront: "#F59E0B",
    "Music Data": "#FB923C",
    "AI Generation": "#F472B6",
    "Asset Upload": "#A78BFA",
    Projects: "#E879F9"
  };
  const color = badges[t.category] ?? "#A1A1AA";
  return <div style={{
    padding: "16px",
    borderRadius: "12px",
    border: "1px solid rgba(255,255,255,0.10)",
    background: "rgba(255,255,255,0.03)",
    marginBottom: "12px"
  }}>
      <div style={{
    display: "flex",
    justifyContent: "space-between",
    alignItems: "center",
    gap: "12px",
    marginBottom: "6px"
  }}>
        <code style={{
    fontFamily: "var(--font-family-mono)",
    fontSize: "15px",
    fontWeight: 600
  }}>
          {name}
        </code>
        <span style={{
    fontSize: "11px",
    fontWeight: 600,
    padding: "2px 10px",
    borderRadius: "999px",
    border: `1px solid ${color}40`,
    background: `${color}1A`,
    color: color
  }}>
          {t.category}
        </span>
      </div>
      {t.callFirst && <div style={{
    fontSize: "11px",
    color: "#00E6E2",
    fontWeight: 600,
    marginBottom: "6px"
  }}>
          ★ Call this FIRST
        </div>}
      <div style={{
    fontSize: "14px",
    lineHeight: 1.5,
    color: "inherit"
  }}>{t.summary}</div>
    </div>;
};

export const TierBadge = ({tier}) => {
  const styles = {
    free: {
      label: "Free",
      color: "#A1A1AA"
    },
    starter: {
      label: "Starter+",
      color: "#00E6E2"
    },
    pro: {
      label: "Pro+",
      color: "#0068FF"
    },
    scale: {
      label: "Scale+",
      color: "#7A5BFF"
    },
    enterprise: {
      label: "Enterprise",
      color: "#FF7A59"
    },
    all: {
      label: "All plans",
      color: "#22C55E"
    }
  };
  const t = styles[tier?.toLowerCase()] ?? styles.all;
  return <span style={{
    display: "inline-flex",
    alignItems: "center",
    gap: "4px",
    padding: "2px 10px",
    borderRadius: "999px",
    border: `1px solid ${t.color}40`,
    background: `${t.color}1A`,
    color: t.color,
    fontSize: "12px",
    fontWeight: 600,
    fontFamily: "var(--font-family-mono)",
    verticalAlign: "middle"
  }}>
      {t.label}
    </span>;
};

export const AICallout = ({page}) => {
  const slug = page ?? "";
  const mdUrl = `https://docs.patchline.ai${slug}.md`;
  return <div style={{
    marginTop: "32px",
    padding: "16px 20px",
    borderRadius: "12px",
    border: "1px solid rgba(0,230,226,0.25)",
    background: "linear-gradient(135deg, rgba(0,230,226,0.08), rgba(0,104,255,0.05))",
    color: "inherit",
    fontSize: "14px",
    lineHeight: 1.6
  }}>
      <strong style={{
    display: "block",
    marginBottom: "6px",
    color: "#00E6E2"
  }}>
        For AI agents reading this page
      </strong>
      The canonical machine-readable version of this page is at{" "}
      <a href={mdUrl}>
        <code>{mdUrl}</code>
      </a>
      . For product actions, connect to{" "}
      <code>www.patchline.ai/api/mcp/v1</code>
      {" "}and call MCP <code>tools/list</code> for the current tool schema.
      Rules for navigating these docs:{" "}
      <a href="https://docs.patchline.ai/AGENTS.md">
        <code>docs.patchline.ai/AGENTS.md</code>
      </a>
      .
    </div>;
};

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.

<TierBadge tier="all" />   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.

<MCPToolCard name="get_started" />

**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.

<MCPToolCard name="analyze_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:**

```json theme={null}
{
  "name": "analyze_url",
  "arguments": {
    "url": "https://open.spotify.com/track/4iV5W9uYEdYUVa79Axb7Rh"
  }
}
```

**Example return:**

```json theme={null}
{
  "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

<MCPToolCard name="browse_catalog" />

**Common arguments:** `page: int` (default 1), `pageSize: int` (default 20, max 50), `artistId: string` (optional roster scope), `includeNonAudio: bool`.

<MCPToolCard name="catalog_search" />

**Arguments:** `query: string` (free text), `limit: int` (default 10), `includeNonAudio: bool`.

<MCPToolCard name="get_asset" />

**Common arguments:** `assetId: string` (the Patchline asset ID), `mode: "summary" | "full"`.

<MCPToolCard name="import_track_from_url" />

**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.

<MCPToolCard name="manage_catalog_asset" />

**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.

<MCPToolCard name="get_audience_overview" />

<MCPToolCard name="get_audience_geo" />

**Common arguments:** `lookbackDays: int` (optional window).

## Artists & roster

<MCPToolCard name="get_artist_intelligence" />

**Common arguments:** `artist_name: string` (required), `mode: "summary" | "full"`.

<MCPToolCard name="search_artists" />

**Arguments:** `query: string` (artist name fragment).

<MCPToolCard name="get_trending_artists" />

**Common arguments:** `genre: string` (optional), `market: string` (ISO2), `min_monthly_listeners: int`, `max_monthly_listeners: int`, `limit: int`.

<MCPToolCard name="refresh_artist_intelligence" />

**Common arguments:** `artistId: string`. Stale-only by default.

<MCPToolCard name="refresh_roster_intelligence" />

**Common arguments:** none required. Refreshes up to 10 stale roster artists.

<MCPToolCard name="add_artist" />

**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).

<MCPToolCard name="remove_artist" />

**Common arguments:** `patchlineArtistId: string`.

<MCPToolCard name="browse_roster" />

**Arguments:** none required; optional filters by enrichment status or genre.

<MCPToolCard name="get_roster_digest" />

**Arguments:** none. Read-only weekly brief.

## Releases

<MCPToolCard name="get_releases" />

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

## Playlists

<MCPToolCard name="find_playlists" />

**Common arguments:** `assetId: string` (preferred catalog track), `spotifyUrl: string` (optional), `limit: int`.

**Gated by:** <TierBadge tier="pro" /> required.

<MCPToolCard name="inspect_playlist" />

**Common arguments:** `playlist_url: string` (Spotify playlist ID or URL), `include_tracks: bool`, `include_curator_network: bool`.

**Gated by:** <TierBadge tier="pro" /> required.

## Smart links & public surfaces

Public share surfaces for owned catalog and releases. Creating one returns a
`shareUrl`; reads and analytics are owner-safe.

<MCPToolCard name="create_smart_link" />

**Common arguments:** `assetId: string`, `title: string` (optional), `enabledSections` (optional section toggles).

<MCPToolCard name="create_drop_link" />

**Common arguments:** `releaseId: string`, optional pre-save / store CTA URLs and `enabledSections`.

<MCPToolCard name="create_asset_share" />

**Common arguments:** `assetId: string`, optional `enabledSections`.

<MCPToolCard name="create_briefing" />

**Common arguments:** markdown body plus validated structured modules and optional Patchline source references.

<MCPToolCard name="list_share_surfaces" />

**Common arguments:** `surfaceType: "drop" | "smartlink" | "asset" | "briefing" | "store"` (optional), `limit: int`.

<MCPToolCard name="get_share_surface" />

**Common arguments:** `url: string` **or** `shareId: string`.

<MCPToolCard name="manage_share_surface" />

**Common arguments:** `shareId: string` plus an update or `revoke` action. Revoke is destructive (unpublishes the surface).

<MCPToolCard name="get_surface_analytics" />

**Common arguments:** `url: string` or `shareId: string`.

<MCPToolCard name="read_public_surface" />

**Common arguments:** `url: string` or `shareId: string`.

## Storefront

<MCPToolCard name="list_store_listings" />

**Arguments:** none required. Read-only readiness + blockers.

<MCPToolCard name="manage_store_listing" />

**Common arguments:** an action (`validate` / `list` / `unlist` / `price` / `reorder` / `update`) plus the listing identifiers.

<MCPToolCard name="create_store_link" />

**Common arguments:** `projectId: string` (optional), `enabledSections` (optional).

<MCPToolCard name="get_store_analytics" />

**Arguments:** none required. Buyer emails are redacted from MCP output.

<MCPToolCard name="get_fan_segments" />

**Arguments:** none required. Aggregates only.

## Music Data

<MCPToolCard name="get_audio_features" />

**Common arguments:** `assetId: string` (preferred), `isrc: string`, or `spotifyTrackUrl: string`.

<MCPToolCard name="get_song_intelligence" />

**Common arguments:** `assetId: string`, `isrc: string`, or `spotifyTrackUrl: string`; optional `mode: "summary" | "full"`.

<MCPToolCard name="get_work_metadata" />

**Common arguments:** `spotifyId`, `spotifyTrackUrl`, or `isrc`.

<MCPToolCard name="find_similar_tracks" />

**Common arguments:** `assetId: string` (a catalog track), `limit: int`.

## AI Generation

<MCPToolCard name="get_bio" />

**Common arguments:** `artist_name: string`.

**Note:** Returns cached bio from intelligence enrichment. No live LLM call. Free.

<MCPToolCard name="generate_pitch" />

**Common arguments:** `artist_name: string`, `track_name: string` (optional), `assetId: string` (optional, preferred for grounding), `target_playlist: string` (optional).

<MCPToolCard name="generate_image" />

**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.

<MCPToolCard name="get_asset_upload_link" />

**Common arguments:** `fileName: string` (extension decides audio vs image). Returns a presigned `uploadUrl` + `assetId`; PUT bytes to it, then call `confirm_asset_upload`.

<MCPToolCard name="create_upload_link" />

**Common arguments:** none required. Returns a secure browser upload link for a human handoff.

<MCPToolCard name="confirm_asset_upload" />

**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.

<MCPToolCard name="create_project" />

**Common arguments:** `artistId: string` (from `add_artist`).

<MCPToolCard name="get_artist_context" />

**Common arguments:** `artistId: string`. Unknown fields return `null` instead of failing.

<MCPToolCard name="create_campaign" />

**Common arguments:** `projectId: string` (from `create_project`). Returns polling guidance.

<MCPToolCard name="get_campaign" />

**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:

1. Call `analyze_url` with the URL.
2. Read the returned `nextSteps`.
3. 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:

```text theme={null}
"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](/catalog/import) 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.

## Related pages

* [MCP overview](/for-agents/mcp-overview) — what MCP is, two-server explainer
* [MCP install](/for-agents/mcp-install) — per-client install
* [AGENTS.md explained](/for-agents/agents-md-explained) — rules of engagement
* [Aria overview](/aria/overview) — same tools, conversation form

<AICallout page="/for-agents/mcp-tools-reference" />