# Epikton agent reference

Search Epikton's music store and listen to previews through MCP (Model Context Protocol). Connect your account to download music covered by your purchases or All Access Pass. New purchases use browser checkout. Compatible browsers and agents can also use WebMCP to assist with store actions.

## Connect

- MCP endpoint: https://epikton.net/wp-json/epikton-agent/v1/mcp
- Transport: stateless Streamable HTTP.
- Authentication: none for the two public, read-only MCP tools.
- Client: a desktop or server-side MCP client.
- Use an MCP client for protocol negotiation and tool discovery. The endpoint is not a human-readable web page. Its MCP requests use POST; JSON bodies are limited to 8 KiB.
- Human setup page: https://epikton.net/agents/

Choose ChatGPT, Claude, Grok, Muse or Other on the setup page. ChatGPT includes web and desktop/Codex instructions. Claude and Grok use their custom-connector settings. Muse can guide creation of a custom connector in chat. Cursor's install link is under Other and opens its confirmation screen.

The copyable setup message helps an assistant configure the connection when the app permits it, or explain the supported steps otherwise. Copying a message does not itself establish a connection. A restart or new chat may be needed after setup.

After connecting, use `tools/list` to confirm that `search_tracks` and `get_track` are available. If setup or verification fails, explain the error before proceeding. Once connected, respond to the person’s own music request.

### Connect for licensed downloads

- Account MCP endpoint: https://epikton.net/wp-json/epikton-agent/v1/mcp/account
- Transport: Streamable HTTP. This connection includes search, previews and `download_track`.
- Authentication: OAuth authorization code with PKCE S256; scope `music:download`. Use the assistant's normal account-connection flow. The customer signs in on Epikton and approves the connection there.
- Discovery: an unauthenticated request returns HTTP 401 with a `WWW-Authenticate` resource metadata URL. The metadata advertises the authorization server and dynamic client registration. Public PKCE clients use token endpoint authentication method `none`; client metadata documents and client-secret grants are not supported.
- In Claude's custom connector setup, select **Sign in now** and **Register automatically (DCR)**. If its initial server check times out, these choices can still be set manually. Do not select the published-identity/CIMD option for this endpoint.
- To receive ZIP attachments in Claude, enable **Code execution and file creation** in **Settings → Capabilities** and allow network access to `epikton.net`. A team owner may need to configure this. Start a new chat after changing network access. MCP connectivity and file-download permission are separate.
- Claude currently documents a 30 MB file limit. If an assistant cannot fetch or attach the ZIP, use the private download link in the browser or download from the signed-in store. See [Claude's file and network settings](https://support.claude.com/en/articles/12111783-create-and-edit-files-with-claude).
- Access lasts 30 days from consent. Access tokens last up to one hour and are renewed with rotating refresh tokens. After 30 days, sign in and approve again. My Account → Connected assistants can disconnect earlier.
- Token renewal tolerates repeated requests for ten seconds; later reuse of an old refresh token disconnects the grant. Access tokens retain their original expiry across renewal; disconnect revokes them all.
- Existing public connections keep their two tools. To download originals, add the account endpoint or replace the public connection with it. Account support depends on the assistant; use the signed-in store if it cannot complete OAuth.

Use `tools/list` after connecting to confirm all three tools. Never ask a customer to paste their password or tokens into a chat.

## Workflow

1. Call `search_tracks` with a concise English title, style, mood or scene query.
2. Offer results using their returned titles. MCP Apps clients can display an inline preview player; use public `preview_url` links when a player is unavailable. Follow `next_offset` with the same query if more results are needed.
3. Call `get_track` with an `id` returned by search for the full public track record.
4. Use the returned `product_url` to continue in the browser. The person signs in and chooses or reviews their license there.
5. Use `download_track` on an authorized account connection for covered tracks, or use the signed-in browser. New purchases use browser checkout.

## Public MCP tools

### search_tracks

Input:

- `query`: required string, 3–160 Unicode characters.
- `offset`: optional integer, 0–10000; defaults to 0.

Example tool arguments:

```json
{"query":"intense action","offset":0}
```

Output: `results` (at most five public track records), `has_more`, `next_offset`, `search_mode` and `search_note`.

Matching uses all query terms in catalog metadata. It is keyword search, not semantic search. There is no automatic translation. Prefer a short English phrase over a long creative brief. An optional phrase such as `120 bpm` matches within 10 BPM; tracks with unknown BPM are excluded for that BPM query.

### get_track

Input: required string `id`, taken from a search result. IDs use `collection-slug:track-slug` and have a maximum length of 220 characters.

Example tool arguments for a currently listed track:

```json
{"id":"action-music:action-thrust"}
```

Output: one public track record. A track may later become unavailable; use current search results as the source of available IDs.

### Public track record

- `id`, `track_slug`, `collection_slug`, `title`, `collection`.
- `description`, `bpm` (an even-numbered estimate; may be null), `bpm_is_approximate`, `moods`, `scenes`. Label known tempos as approximate.
- `preview_url`: public MP3 preview that can be played or downloaded. It is not an original file or a usage license.
- `product_url`: browser handoff to the matching licensing product and track.
- `license_options`: published purchase choices, prices and currency. Prices describe new purchases; checkout determines discounts and the final charge.
- `access_note`: guidance for owned tracks, All Access and guest purchases.

Use `product_url` to sign in, purchase a license or download a track in the browser.

## Account download tool

### download_track

Input: the required `id` returned by search, with the same format and length limits as `get_track`.

Output: `id`, `title`, `download_url`, `filename`, `mime_type` (`application/zip`), `expires_at` (UTC) and `download_note`.

Download the returned private link within five minutes. It works without an additional browser login and can be used by an assistant's file-download tool. Treat it as a temporary credential: do not publish or log it. Preparing a link does not transfer the file; verify the download completed before reporting success. Clients that cannot fetch files may present the private link to the connected customer.

The account's current access is checked again when the file is requested. An expired or disconnected link returns HTTP 403; request a new link after restoring access. A missing original returns a service error, not a fallback to a public original-file URL. HEAD checks and byte-range downloads are supported. Respect `Retry-After` on HTTP 429.

If the track is not covered, use `product_url` to review licensing in the browser. If an earlier guest purchase is missing, sign in on Epikton with the checkout email before purchasing again.

### Inline previews

Both tools declare an MCP Apps player at `ui://epikton/track-previews-v1`. Supporting clients load it with `resources/read` using MIME type `text/html;profile=mcp-app`. The player receives the tool result and offers playback controls for its public previews. Playback starts only when the person presses play. Clients without MCP Apps support can use the same results as text and preview links.

## REST API

Services that use an HTTP API can access the same search results and public track records without MCP negotiation.

- Base URL: `https://epikton.net/wp-json/epikton-agent/v1`
- OpenAPI document: https://epikton.net/wp-json/epikton-agent/v1/openapi.json
- Authentication: none. Use a server-side client; foreign browser origins are rejected.
- `GET /tracks?query=intense%20action&offset=0`: the same search input limits, five-result pagination and output as `search_tracks`. Query-string `offset` must be a decimal integer from 0 to 10000.
- `GET /tracks/action-music:action-thrust`: the same public record as `get_track`. Use a current search result's `id`.

Send only the documented query parameters, with no request body. Responses are JSON. Invalid input returns HTTP 400, an unavailable track returns 404, and temporary service failures return 503. HTTP 429 responses include `Retry-After` in seconds. Follow that delay instead of immediately retrying. API calls, including OpenAPI discovery, share the MCP allowance of 120 requests per IP per minute.

Use the returned preview URL to play or download an MP3 preview and the product URL for browser licensing. Original downloads use the authorized account MCP connection or the signed-in browser.

## WebMCP browser tools

WebMCP is experimental. Availability depends on the browser and agent. Open the store to search, or a track's product page to add it to the cart or download it.

- Store page, https://epikton.net/store/: `epikton_find_licensing_tracks` accepts `query` and optional `offset` with the same search limits as MCP.
- Matching licensing product page: `epikton_add_licensing_track_to_cart` accepts `track` containing the returned `track_slug`. It adds one Universal License to the cart. The person completes checkout in the browser.
- Matching licensing product page: `epikton_download_licensed_track` accepts `track`. Sign in with an account whose purchase or All Access Pass covers the track.

A download result confirms that a download was requested, not that delivery completed. Check the browser's download status. If WebMCP is unavailable, use the visible store controls.

## Available music and licensing

Search tracks available for licensing in Action Music, Epic Music, Horror Music, Hybrid, Sci-Fi, Ticking Clock and Cinematic Vocals.

Previews are free to listen to. Using a track in a project requires a license. Sign in on the track's store page to download music covered by your purchase or All Access Pass at no extra cost.

## Limits and recovery

- MCP and REST API combined: 120 requests per IP per minute, including initialization and discovery. The allowance resets every 60 seconds. People sharing an IP share this quota.
- For HTTP 429 responses, wait for the duration in `Retry-After` before retrying. Server traffic controls can also temporarily limit requests.
- Account MCP, product-page and WebMCP original downloads share 60 GET starts per account in a rolling ten-minute window. Range and resume GETs count as starts; HEAD checks do not. Requests denied before file delivery do not count.
- Account MCP can prepare up to 120 download links per account per minute, also subject to the shared MCP IP quota. Links expire after five minutes.
- OAuth setup limits: 120 new client registrations per IP per minute and 1,000 site-wide per day; token and revocation requests share 120 per IP per minute. Sign-in starts allow 30 per IP per five minutes, and consent screens allow 30 per account per five minutes. A customer can have up to 20 active assistant connections. Registration records last one year; a client whose registration expires must register again.
- The sign-in handoff expires after 20 minutes; consent requests and authorization codes expire after five minutes. Restart connection setup if they expire. Grant lifetime is 30 days, even if tokens are refreshed.
- Downloads through purchase receipt or account order links may have separate limits.
- Refresh or sign in again if the browser session expires.
- If a previous cart action has an unknown result, refresh and inspect the cart before retrying.
- If a guest purchase is missing from the account, use Epikton's email sign-in with the address used at checkout before purchasing again.