MCP server overview

The Model Context Protocol (MCP) is an open standard for giving AI tools access to external services as callable functions. Patchline ships two MCP servers — one for your product data, one for these docs. Both are public, both speak the same protocol, but they serve different purposes. Tools requiring user-scoped data (catalog, roster, etc.) need an authenticated session via OAuth 2.0 with PKCE.

Two MCP servers

This is the most-important distinction on this page. Don’t conflate them.

	Product MCP	Docs MCP
URL	`https://www.patchline.ai/api/mcp/v1`	`https://docs.patchline.ai/mcp`
What it exposes	Product tools that act on your music data	2 tools that search & read these docs
Auth	OAuth 2.0 with PKCE (user-scoped)	Public, no auth
Built by	Patchline	Mintlify (auto-generated)
Use it when	You want the AI to do something with your catalog / roster / releases	You want the AI to learn about how Patchline works
Example	”Find playlists for this track” → `find_playlists`	”How does the release planner work?” → `search`

If in doubt: install the product MCP. It can answer most docs questions implicitly by knowing the tool surface; it can also act.

What MCP is (60-second primer)

MCP is a protocol from Anthropic that lets AI tools (Claude, Cursor, ChatGPT, Codex) call external functions safely. Think of it like a “plugin standard” for AI:

Server (Patchline) exposes tools — named functions with typed arguments and return values.
Client (your AI tool) connects to the server, gets the list of tools, and decides when to call them based on user conversation.
Calls are made on demand. Results stream back into the AI’s response.

Why this matters: Patchline isn’t a chatbot you have to switch to. It’s a set of tools your existing AI gains. Ask Cursor “find playlists for my new track” and Cursor calls Patchline directly. No copy-paste.

Core product tools

Grouped by category. This page documents the stable public tool families. For the exact current tool list, connect an MCP client and run tools/list.

Dispatch

Catalog

Artists & roster

Releases

Playlists

Smart links

Music data

AI generation

Additional tool families

The tools above are the stable, most-used surface. The MCP server also exposes additional tool families 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 exact, current list with full schemas, connect an MCP client and run tools/list. That response is the canonical source of truth and updates without a docs release.

How auth works

Patchline’s product MCP uses OAuth 2.0 with PKCE — the same flow Spotify, Google, GitHub, and every modern OAuth server uses. Concretely:

You add the Patchline MCP URL to your AI client’s config.
First time you make a tool call, your client opens a browser to patchline.ai.
You sign in (or are already signed in) to Patchline.
You approve the AI client’s access.
The client gets a bearer token and uses it for every subsequent 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 its OAuth metadata at:

https://www.patchline.ai/.well-known/oauth-protected-resource

Per RFC 9728. Your client uses this to discover the authorization endpoint and required scopes automatically.

Tier gating

Every tier can install and connect the MCP server. Tool calls consume your AI credit pool just like Aria chat does:

Tier	AI credits / month	Practical use
	100	Try a few tools, ~50 calls
	1,000	Daily use for one artist
	5,000	Heavy use, roster of 5
	20,000	Label-scale automation
	Unlimited	Programmatic / agent-driven

Some tools have tier requirements beyond credit cost:

find_playlists, inspect_playlist — Pro+ (same as the web feature)
add_artist beyond your roster limit — gated by tier limit (Free 1, Starter 1, Pro 5, Scale 20, Ent unlimited)

If a call hits a tier gate, the MCP server returns a 403 with an upgrade-path message. Your client surfaces it.

Installation

Install the MCP server → One-line install for Cursor (URL config), one-command for Codex (codex mcp add aria --url …), JSON snippet for Claude Desktop and VS Code. Patchline ships a 1-click “Add to Cursor” deeplink directly from this docs site (top-right of any page).

Example: from zero to first tool call

// Cursor — paste this into Settings > MCP > Add new MCP server
{
  "mcpServers": {
    "aria": {
      "url": "https://www.patchline.ai/api/mcp/v1"
    }
  }
}

Then in Cursor chat:

You: "Find playlists I should pitch my track to:
      https://open.spotify.com/track/4iV5W9uYEdYUVa79Axb7Rh"

Cursor recognizes the URL, calls analyze_url, which resolves the track, then calls find_playlists (after OAuth handshake if not yet authenticated). Returns 10 ranked matches inline. Total time: ~5 seconds + first-run OAuth (~30 seconds).

Rules of engagement for AI agents

If you’re an AI agent reading this page programmatically, use these rules of engagement and confirm exact schemas with MCP tools/list:

ALWAYS call analyze_url first when a user pastes a streaming 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.

Performance

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

MCP install — per-client install steps
MCP tools reference — full schemas per tool
Claude plugin — the higher-level alternative for Claude
AGENTS.md explained — what /AGENTS.md and /llms.txt are for
Aria overview — Aria is the MCP tools, in chat form

FAQ

Do MCP tool calls cost me money?

They consume AI credits from your monthly pool — same pool as Aria chat. The MCP server itself is free to install and connect.

Can I write my own MCP client?

Yes. The MCP protocol is open. Patchline’s server implements MCP spec version 2025-03-26. See modelcontextprotocol.io for the spec. OAuth metadata is at /.well-known/oauth-protected-resource.

Why two MCP servers?

Product MCP acts on user data (authenticated, write-capable). Docs MCP searches public docs (unauthenticated, read-only). Different auth models, different data, different purposes. Both ship because AI tools benefit from both.

Can I use this MCP server 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.

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.

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 is a higher-level wrapper that adds a Patchline-specific progressive interview workflow on top of the same tools. If you use Claude, the plugin is the better start.

Where do I report bugs?

GitHub: github.com/Patchline-AI/aria/issues for plugin + MCP issues. Email support@patchline.ai for account issues.

Documentation Index

​Two MCP servers

​What MCP is (60-second primer)

​Core product tools

​Dispatch

​Catalog

​Artists & roster

​Releases

​Playlists

​Smart links

​Music data

​AI generation

​Additional tool families

​How auth works

​Tier gating

​Installation

​Example: from zero to first tool call

​Rules of engagement for AI agents

​Performance

​Related pages

​FAQ