Install the Patchline MCP server

Pick your client. Each install is one config snippet or one command — about 30 seconds. Authentication runs the first time you make a tool call (browser-based OAuth 2.0 with PKCE). Free to install on every tier.

The endpoint

For every client, the URL is the same:

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

Cursor

Open Cursor settings

Cmd / Ctrl + , → MCP in the sidebar → + Add new MCP server.

Paste the config

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

Authenticate on first call

The first tool call opens a browser to patchline.ai. Sign in (or Google OAuth), approve the connection, return to Cursor. You’re set.

1-click install: open this URL on the same machine running Cursor — it triggers Cursor’s MCP deeplink installer:

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

Or use the “Install in Cursor” button at the top of any page in these docs (via the contextual menu).

Codex

Enable remote MCP

In ~/.codex/config.toml, set:

experimental_use_rmcp_client = true

Add the server

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

Authenticate on first call

Codex opens the browser, you sign in to Patchline, return to Codex. Tokens cached locally.

VS Code (with Copilot or any MCP-aware extension)

Create or edit .vscode/mcp.json

In your workspace root, create .vscode/mcp.json (or merge with an existing one):

{
  "servers": {
    "aria": {
      "type": "http",
      "url": "https://www.patchline.ai/api/mcp/v1"
    }
  }
}

Reload VS Code

Reload the window so the extension picks up the new server.

Authenticate on first call

Same browser-based OAuth flow.

Alternate: if your extension doesn’t support direct HTTP transport, use mcp-remote to bridge:

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

Claude Desktop

Open Claude Desktop config

Settings → Developer → Edit Config. Opens claude_desktop_config.json.

Add the Patchline server

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

Restart Claude Desktop

Quit and relaunch. Aria appears in the connectors list.

Authenticate on first call

Browser-based OAuth.

Recommended for Claude users: use the official Patchline Claude plugin instead. It wraps the same MCP server with the Aria moment skills (drop a track, make a smart link, know your fans, run your day) for music release work.

Claude Code

Claude Code has its own plugin command. Three steps:

Add the marketplace

/plugin marketplace add Patchline-AI/aria

Install the plugin

/plugin install aria@patchline-ai
/reload-plugins

Authenticate

Run:

/mcp

Then authenticate plugin:aria:aria. Browser OAuth opens.

This is the recommended path for Claude Code. The plugin ships with extra context: the Aria moment skills (drop, link, fans, operator) and a get-started flow grounded in your real catalog.

ChatGPT / OpenAI ChatGPT app

ChatGPT’s MCP support is in early access at time of writing. When it lands publicly, point ChatGPT’s MCP config at https://www.patchline.ai/api/mcp/v1 with the same OAuth flow as the other clients.

Any other MCP-compatible client

Patchline implements the MCP spec version 2025-03-26. Any compliant client should work with this config shape:

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

OAuth discovery is at /.well-known/oauth-protected-resource per RFC 9728.

Verify your install

After authenticating, ask your AI:

What MCP tools do you have available?

You should see a long list of Patchline tools (catalog, artists, releases, playlists, smart links, music data, AI generation). If you see them, you’re connected. Test a real call:

Paste a Spotify URL → AI calls analyze_url → returns track identity.

If the first call fails with unauthenticated, your client may have skipped the OAuth flow — disconnect and reconnect, the browser should open.

What to try first

Once you’re connected, you don’t call tools by name — you just say what you want and the AI picks the right tool. Try these:

Say this	What happens
”get started”	Aria reports your workspace and the single best next move.
Paste a Spotify track URL	`analyze_url` resolves it and suggests the next steps.
”make a smart link for my latest release”	`create_smart_link` returns one link routing fans to every platform.
”drop my new single”	Takes a track to a live store listing and a shareable release page.
”who are my fans and where are they”	Aggregate audience overview plus city-level geography.
”find playlists for my track”	Ranked playlist opportunities by sonic fit (Pro+ required).
“what should I do this week”	A prioritized roster digest of cleanup and next actions.

In Claude, the Aria plugin packages these as guided moment skills — drop, link, fans, and operator — so one phrase runs a whole flow, grounded in your real catalog.

Pricing

Plans, AI credits, and limits live on the pricing page — we keep them there so they’re always current.

MCP overview — what MCP is, two-server explanation
MCP tools reference — full schemas per tool
Claude plugin — the higher-level Claude alternative
AGENTS.md explained — rules of engagement

Troubleshooting

Cursor says 'MCP server failed to connect'

Most likely the URL is missing https:// or has a trailing slash. The correct value is exactly https://www.patchline.ai/api/mcp/v1 — no trailing /.

The browser opened but never came back

Check the URL the browser opened — it should be https://patchline.ai/api/mcp/v1/authorize?.... If you saw a localhost: URL, your client is using loopback callback and got blocked by a firewall. Try a different network or check firewall settings.

I get '403 Forbidden' on certain tools

Tier-gated tool. find_playlists and inspect_playlist require Pro+. Upgrade or use a different tool.

The OAuth window says 'invalid_redirect_uri'

Your client’s redirect URI isn’t registered with Patchline. Email support@patchline.ai with the URI your client uses — we’ll add it.

How do I disconnect?

Patchline Settings → Security → Connected applications → revoke Aria MCP. Next call from the client will re-prompt OAuth.

Can I install both this and the docs MCP?

Yes — they’re separate servers with separate names. Most users install both: docs MCP for learning Patchline, product MCP for acting on data. See MCP overview for the distinction.

Patchline MCP — your music data in your AI

Claude

Agent discovery

Docs MCP (for AI agents)

Install the Patchline MCP server

The endpoint

Cursor

Codex

VS Code (with Copilot or any MCP-aware extension)

Claude Desktop

Claude Code

ChatGPT / OpenAI ChatGPT app

Any other MCP-compatible client

Verify your install

What to try first

Pricing

Troubleshooting

​The endpoint

​Cursor

​Codex

​VS Code (with Copilot or any MCP-aware extension)

​Claude Desktop

​Claude Code

​ChatGPT / OpenAI ChatGPT app

​Any other MCP-compatible client

​Verify your install

​What to try first

​Pricing

​Related pages

​Troubleshooting

The endpoint

Cursor

Codex

VS Code (with Copilot or any MCP-aware extension)

Claude Desktop

Claude Code

ChatGPT / OpenAI ChatGPT app

Any other MCP-compatible client

Verify your install

What to try first

Pricing

Related pages

Troubleshooting