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

# Connect an agent (MCP)

> Give Claude, Cursor or any MCP client direct access to the vinyl catalog.

Open Vinyl runs an [MCP](https://modelcontextprotocol.io) server at:

```
https://api.openvinyl.dev/mcp
```

No key needed; the same [rate limits](https://docs.openvinyl.dev/api-reference/introduction.md#rate-limits) apply. Each tool returns the same JSON as the matching REST endpoint.

## Install

```bash Claude Code theme={null}
claude mcp add --transport http open-vinyl https://api.openvinyl.dev/mcp
```

```json Claude Desktop / Cursor (mcp.json) theme={null}
{
  "mcpServers": {
    "open-vinyl": {
      "type": "http",
      "url": "https://api.openvinyl.dev/mcp"
    }
  }
}
```

## Tools

| Tool | Use it for | REST equivalent |
| - | - | - |
| `lookup_barcode` | A barcode from the back cover. The most reliable input. | `GET /v1/albums?barcode=` |
| `search_albums` | Artist and/or title, any order | `GET /v1/albums?q=` |
| `get_album` | One album's details and links | `GET /v1/albums/{id}` |
| `list_pressings` | An album's pressings, filtered, with facet counts | `GET /v1/albums/{id}/pressings` |
| `find_pressings_by_code` | Catalog number, runout etching or barcode | `GET /v1/search` |
| `get_pressing` | Everything about one pressing | `GET /v1/pressings/{id}` |

The server also sends instructions on how to identify a record (barcode first, then narrow with facets), so agents follow the same flow as [Identify a record](https://docs.openvinyl.dev/guides/identify-a-record.md).

## Getting started

Once the server is connected, the agent introduces what it can do the first time you use it: identify a record from a barcode, artist and title, catalog number or runout, narrow it to the exact pressing, and show the tracklist. Then it asks what record you have.

In Claude Code you can also run the `start` prompt any time: `/mcp__open-vinyl__start`.

Errors (an unknown album, a malformed barcode) come back as tool errors with the API's message.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.