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

# Patchline MCP — your music data in your AI

> Patchline ships an MCP server at www.patchline.ai/api/mcp/v1 that routes your entire music infrastructure — catalog, artist intelligence, releases, playlists, smart links, music data — directly into Cursor, Codex, Claude, VS Code, and any MCP-compatible AI client. OAuth 2.0 with PKCE. One command to install.

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>;
};

Your entire catalog, routed directly into your AI.

The **Patchline MCP server** connects Cursor, Codex, Claude Desktop,
Claude Code, VS Code — any MCP-compatible client — straight to your
Patchline account. Catalog, artist intelligence, releases, playlists,
smart links, music data: every Aria capability becomes a callable tool
your AI can use without leaving its window.

**Endpoint:** `https://www.patchline.ai/api/mcp/v1`
**Auth:** OAuth 2.0 with PKCE — your credentials never touch the AI client.
**Install:** one command or one config snippet.

<TierBadge tier="all" />   Free to install on every tier.

## Why this matters

Stop copy-pasting ISRC codes. Stop screenshotting your Spotify
dashboard into ChatGPT. Stop re-explaining your catalog every chat.

Patchline routes your music business into the AI tool you already use:

* **In Cursor / Codex / VS Code:** *"Find playlists for my new track"* —
  the AI calls Patchline directly, pitches come back ranked, with
  reasoning.
* **In Claude Desktop / Claude Code:** *"What's Mira's audience
  trajectory and which release should I prioritize?"* — Aria's full
  knowledge of your roster surfaces in the chat.
* **In any MCP-compatible client:** the same tools, same data, same OAuth.

This is not a chatbot you switch to. It's a set of tools your existing
AI gains.

## What's actually exposed

Grouped by category. The MCP server exposes the live product surface —
the exact list and schemas refresh with the product. Connect a client
and run `tools/list` for the authoritative inventory.

### Dispatch — always call this first

<MCPToolCard name="analyze_url" />

### Catalog

<MCPToolCard name="browse_catalog" />

<MCPToolCard name="catalog_search" />

<MCPToolCard name="get_asset" />

### Artists & roster

<MCPToolCard name="get_artist_intelligence" />

<MCPToolCard name="search_artists" />

<MCPToolCard name="get_trending_artists" />

<MCPToolCard name="add_artist" />

<MCPToolCard name="remove_artist" />

### Releases & projects

<MCPToolCard name="get_releases" />

### Playlists

<MCPToolCard name="find_playlists" />

<MCPToolCard name="inspect_playlist" />

### Smart links

<MCPToolCard name="create_smart_link" />

### Music data

<MCPToolCard name="get_audio_features" />

<MCPToolCard name="get_song_intelligence" />

<MCPToolCard name="get_work_metadata" />

### AI generation

<MCPToolCard name="get_bio" />

<MCPToolCard name="generate_pitch" />

### Additional tool families

The MCP server also exposes additional tools that evolve with the
product:

* **Projects & campaigns** — create release projects, build campaign
  plans, fetch artist context.
* **Public surface links** — generate drop links, pitch links, media
  kits, briefings, and shareable asset links.
* **Catalog upload** — get signed upload URLs and confirm finished
  uploads from agents that fetch audio.
* **Similarity** — find tracks with similar audio characteristics to a
  given catalog asset.

For the canonical, current list with full schemas, **connect an MCP
client and run `tools/list`**.

## Install

[**Install the MCP server →**](/for-agents/mcp-install)

Cursor, Codex, Claude Desktop, Claude Code, VS Code — each has a
one-command or one-snippet install. Cursor and VS Code support a
1-click install button.

The fastest path:

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

Paste that into Cursor → Settings → MCP → **+ Add new MCP server**.
First tool call triggers OAuth.

## How auth works

Patchline's MCP server uses **OAuth 2.0 with PKCE** — the same flow
Spotify, Google, GitHub use:

1. You add the Patchline MCP URL to your client's config.
2. First tool call opens a browser to `patchline.ai`.
3. You sign in (or are already signed in) to Patchline.
4. You approve the AI client's access.
5. The client receives a bearer token and uses it for every call.

**Your credentials never touch the AI client.** Tokens are bound to
the client, revocable from Patchline Settings, and expire on a
schedule.

The MCP server publishes OAuth metadata at:

```text theme={null}
https://www.patchline.ai/.well-known/oauth-protected-resource
```

Per RFC 9728 — your client uses this to discover the authorization
endpoint and scopes automatically.

## What MCP is (60-second primer)

MCP (Model Context Protocol) is an open standard from Anthropic that
lets AI clients call external functions safely. Think of it as a
"plugin standard" for AI:

1. **Server** (Patchline) exposes tools — named functions with typed
   arguments and return values.
2. **Client** (your AI tool) connects to the server, gets the tool
   list, and decides when to call them based on conversation.
3. **Calls** happen on demand. Results stream back into the AI's
   response, inline.

Patchline implements MCP spec version `2025-03-26`. Any compliant
client can connect.

## Example: from zero to first tool call

After installing (above):

```text theme={null}
You: "Find playlists I should pitch my track to:
      https://open.spotify.com/track/4iV5W9uYEdYUVa79Axb7Rh"
```

What happens:

1. Cursor recognizes the URL.
2. Cursor calls `analyze_url` → Patchline resolves the track identity.
3. Cursor calls `find_playlists` (after first-run OAuth).
4. 10 ranked matches return inline, each with a reason.

Total time: \~5 seconds + first-run OAuth (\~30 seconds).

## Rules of engagement for AI agents

If you're an AI agent reading this programmatically, confirm exact
schemas with MCP `tools/list`, then follow these rules:

* **ALWAYS call `analyze_url` first** when the user pastes a
  streaming-platform URL.
* **NEVER call `add_artist` name-only** — always include a platform URL.
* **PREFER cached `get_artist_intelligence`** over re-enriching.
* **For docs navigation rules**, see
  [`docs.patchline.ai/AGENTS.md`](https://docs.patchline.ai/AGENTS.md).

## Performance

* **Latency:** Most tools return in under 500ms. Tools that refresh
  provider-backed data or run analysis take 2–5s on cold-cache.
  Cached results return in under 200ms.
* **Rate limits:** None published; you'll hit your AI credit budget
  long before any rate limit.
* **Idempotency:** Read tools are idempotent. Write tools
  (`add_artist`, `create_smart_link`) are not — calling twice creates
  two entries.

## Related pages

* [Install the MCP server](/for-agents/mcp-install) — per-client install steps
* [MCP tools reference](/for-agents/mcp-tools-reference) — full schemas per tool
* [Claude plugin](/for-agents/claude-plugin) — higher-level Claude alternative
* [Aria overview](/aria/overview) — Aria *is* the MCP tools, in chat form
* [AGENTS.md explained](/for-agents/agents-md-explained) — discovery files for AI agents

## FAQ

<AccordionGroup>
  <Accordion title="Do MCP tool calls cost me money?">
    They consume AI credits from your monthly pool — same pool as Aria
    chat. The server itself is free to install and connect.
  </Accordion>

  <Accordion title="Can I write my own MCP client?">
    Yes. MCP is an open protocol. Patchline's server implements spec
    version `2025-03-26`. See modelcontextprotocol.io. OAuth metadata
    is at `/.well-known/oauth-protected-resource`.
  </Accordion>

  <Accordion title="What's the difference between the MCP server and the Claude plugin?">
    The MCP server is the raw tool surface — any MCP client can use it.
    The [Claude plugin](/for-agents/claude-plugin) wraps the same
    tools with the Aria moment skills (drop, link, fans, operator) for
    music release work. If you use Claude, the plugin is the
    better start.
  </Accordion>

  <Accordion title="Is there a public REST API?">
    Enterprise tier includes API access. The MCP server is the
    recommended interface for everyone else — same data, lower
    integration cost, AI-native.
  </Accordion>

  <Accordion title="Can I use this with non-AI tools?">
    Technically yes — anything that speaks MCP and can complete the
    OAuth flow. In practice it's almost always an AI client.
  </Accordion>

  <Accordion title="Where do I report bugs?">
    GitHub: [github.com/Patchline-AI/aria/issues](https://github.com/Patchline-AI/aria/issues)
    for plugin + MCP issues. Email
    [support@patchline.ai](mailto:support@patchline.ai) for account issues.
  </Accordion>
</AccordionGroup>

***

## Also: a docs MCP

In addition to the product MCP above, Patchline runs a small **docs
MCP** at `https://docs.patchline.ai/mcp` — read-only access to this
documentation, so your AI client can search and read the docs natively
instead of crawling URLs.

It's a different server, different URL, no auth. Useful if you want
your AI to learn Patchline without needing access to your account.

[Install the docs MCP →](/for-agents/install-docs-mcp)

If you're not sure which to install: **install the product MCP**. It
covers everything the docs MCP can answer (because the AI can simply
call `tools/list` and get the live surface) plus everything the docs
MCP can't (acting on your data).

<AICallout page="/for-agents/mcp-overview" />