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

# Install the Patchline MCP server

> Step-by-step install for the Patchline product MCP server in Cursor, Codex, Claude Desktop, Claude Code, and VS Code. One config snippet or one command per client. First tool call opens browser-based OAuth — your credentials never touch the AI client.

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

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

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

## The endpoint

For every client, the URL is the same:

```text theme={null}
https://www.patchline.ai/api/mcp/v1
```

## Cursor

<Steps>
  <Step title="Open Cursor settings">
    Cmd / Ctrl + `,` → **MCP** in the sidebar → **+ Add new MCP server**.
  </Step>

  <Step title="Paste the config">
    ```json theme={null}
    {
      "mcpServers": {
        "aria": {
          "url": "https://www.patchline.ai/api/mcp/v1"
        }
      }
    }
    ```
  </Step>

  <Step title="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.
  </Step>
</Steps>

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

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

<Steps>
  <Step title="Enable remote MCP">
    In `~/.codex/config.toml`, set:

    ```toml theme={null}
    experimental_use_rmcp_client = true
    ```
  </Step>

  <Step title="Add the server">
    ```bash theme={null}
    codex mcp add aria --url https://www.patchline.ai/api/mcp/v1
    ```
  </Step>

  <Step title="Authenticate on first call">
    Codex opens the browser, you sign in to Patchline, return to Codex.
    Tokens cached locally.
  </Step>
</Steps>

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

<Steps>
  <Step title="Create or edit .vscode/mcp.json">
    In your workspace root, create `.vscode/mcp.json` (or merge with an existing one):

    ```json theme={null}
    {
      "servers": {
        "aria": {
          "type": "http",
          "url": "https://www.patchline.ai/api/mcp/v1"
        }
      }
    }
    ```
  </Step>

  <Step title="Reload VS Code">
    Reload the window so the extension picks up the new server.
  </Step>

  <Step title="Authenticate on first call">
    Same browser-based OAuth flow.
  </Step>
</Steps>

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

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

## Claude Desktop

<Steps>
  <Step title="Open Claude Desktop config">
    Settings → **Developer** → **Edit Config**. Opens
    `claude_desktop_config.json`.
  </Step>

  <Step title="Add the Patchline server">
    ```json theme={null}
    {
      "mcpServers": {
        "aria": {
          "url": "https://www.patchline.ai/api/mcp/v1",
          "transport": "http"
        }
      }
    }
    ```
  </Step>

  <Step title="Restart Claude Desktop">
    Quit and relaunch. Aria appears in the connectors list.
  </Step>

  <Step title="Authenticate on first call">
    Browser-based OAuth.
  </Step>
</Steps>

<Note>
  **Recommended for Claude users:** use the official
  [Patchline Claude plugin](/for-agents/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.
</Note>

## Claude Code

Claude Code has its own plugin command. Three steps:

<Steps>
  <Step title="Add the marketplace">
    ```bash theme={null}
    /plugin marketplace add Patchline-AI/aria
    ```
  </Step>

  <Step title="Install the plugin">
    ```bash theme={null}
    /plugin install aria@patchline-ai
    /reload-plugins
    ```
  </Step>

  <Step title="Authenticate">
    Run:

    ```bash theme={null}
    /mcp
    ```

    Then authenticate `plugin:aria:aria`. Browser OAuth opens.
  </Step>
</Steps>

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:

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

```text theme={null}
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:

```text theme={null}
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](/for-agents/claude-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](https://patchline.ai/pricing) — we keep them there so they're always current.

## Related pages

* [MCP overview](/for-agents/mcp-overview) — what MCP is, two-server explanation
* [MCP tools reference](/for-agents/mcp-tools-reference) — full schemas per tool
* [Claude plugin](/for-agents/claude-plugin) — the higher-level Claude alternative
* [AGENTS.md explained](/for-agents/agents-md-explained) — rules of engagement

## Troubleshooting

<AccordionGroup>
  <Accordion title="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 `/`.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="I get '403 Forbidden' on certain tools">
    Tier-gated tool. `find_playlists` and `inspect_playlist` require
    Pro+. Upgrade or use a different tool.
  </Accordion>

  <Accordion title="The OAuth window says 'invalid_redirect_uri'">
    Your client's redirect URI isn't registered with Patchline. Email
    [support@patchline.ai](mailto:support@patchline.ai) with the URI
    your client uses — we'll add it.
  </Accordion>

  <Accordion title="How do I disconnect?">
    Patchline Settings → Security → Connected applications → revoke
    Aria MCP. Next call from the client will re-prompt OAuth.
  </Accordion>

  <Accordion title="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-agents/mcp-overview) for
    the distinction.
  </Accordion>
</AccordionGroup>

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