for agents

start at plyr.fm/llms.txt, also available on the docs domain. This guide is available as plain Markdown.

plyr.fm offers public audio discovery and authenticated library management. An integration should be able to find a track, inspect what it found, and hand back a playable link. Publishing or changing a library is a separate action that needs the user’s authorization.

choose an interface

what you are doing	use	why
asking a chat assistant to find audio or inspect a library	hosted MCP: https://plyrfm.fastmcp.app/mcp	focused read tools; no local package setup
running those agent tools locally	uvx --prerelease=allow plyrfm-mcp	same interface with local credentials and backend selection
working in a terminal, including uploads and library edits	CLI: uvx plyrfm --help	explicit commands and readable output
composing a Python application or repeatable workflow	SDK: PlyrClient / AsyncPlyrClient	typed results, sync/async composition, reads and authorized writes
using another language, precise schemas, or API-only services	HTTP: https://api.plyr.fm/openapi.json	the full API, including features not wrapped by the SDK
listening in a browser	https://plyr.fm/track/{id}	opens the player for the listener

The CLI also handles reads. Its display output is for a terminal; use SDK objects or HTTP JSON when another program consumes the result. MCP is read-only and does not control the web player’s queue. Browser sessions, radio and jams are examples of API capabilities outside the SDK namespaces.

The SDK, CLI, and MCP live in plyr-python-client. Their capability table records each SDK operation’s CLI/MCP mapping and explains deliberate omissions. Parity means shared behavior agrees; it does not require every API endpoint to become a tool. The interface guide explains the contract checks and Pi evaluation workflow.

discover the MCP

Connect your MCP client to https://plyrfm.fastmcp.app/mcp, or launch uvx --prerelease=allow plyrfm-mcp as a local stdio server. Public catalog tools need no token. For account reads, the local server accepts PLYR_TOKEN; the hosted server accepts the x-plyr-token header. Create tokens in settings → developer.

Discover tools when connecting. Read plyr://interfaces for interface guidance and plyr://me for your authenticated identity. The current groups are:

• find audio: search, top_tracks, list_tags, tracks_by_tag, list_tracks
• inspect a selection: get_track, get_playlist, playlists_by_artist
• read your library: my_tracks, liked_tracks, list_playlists, list_revisions
• explore a playlist: playlist_recommendations

Library reads and playlist recommendations require authentication; revision reads also require ownership. A tool’s presence does not mean the current caller can read every resource.

find something, then inspect it

search(query="ambient", type="tracks", limit=5)
→ results with type, id, title, artist, and relevance
get_track(track_id=<chosen result id>)
→ track metadata and an audio URL

Search accepts 2–100 characters. type uses plural names such as tracks, artists, albums, tags, or playlists; each result has a singular type discriminator. The limit is per type, from 1 to 50. counts counts returned results, not every match in the catalog. There is no search offset; narrow the query, or use the browse endpoints documented in OpenAPI.

Search is lexical/fuzzy matching. Do not treat a title match as evidence of a track’s sound. Mood search is a separate, feature-flagged app capability; the MCP search tool exposes the lexical search interface.

Read the chosen track’s description and tags, and distinguish its identifiers:

• id identifies the track in this plyr.fm environment.
• atproto_record_uri is its ATProto record address, when available. Resolve a known public URI through GET /tracks/by-uri?uri=....
• file_id identifies audio storage; it is not a track ID.
• r2_url in HTTP and hosted MCP JSON responses is the audio URL. Python SDK objects expose it as audio_url. The URL may point to a CDN or an authenticated route.

Inspect visibility, gated, and any labels before offering access. Missing metadata and null duration are unknown values. The full HTTP response can contain fields that a released SDK/MCP model does not yet expose.

listen, share, or download

Return the track page, https://plyr.fm/track/{id}, when the user wants to listen. MCP discovery does not control the web player’s queue or start audio in the user’s browser.

For a custom player, use the returned audio URL and handle redirects and access errors. There is no /tracks/{id}/stream endpoint. A metadata lookup succeeding proves the record was found; an audio request succeeding proves bytes are reachable; neither proves that playback started on the user’s device.

Downloads follow the artist’s policy and the dedicated download endpoints. Streaming availability alone does not establish download permission. See the creator guide for the current behavior.

make an authorized change

Use the SDK, CLI, or HTTP API for uploads, likes, comments, and playlist edits. Obtain the user’s authorization for the intended change; possessing a token is not itself authorization. Public writes may also publish to the user’s PDS.

After a write, read the resource again: check the track detail after editing it, or the playlist’s ordered tracks after changing its contents. An upload may finish before background audio optimization, PDS mirroring, or indexing finishes. If a request times out, inspect state before repeating a create operation so you do not publish duplicates.

A browser session uses an HttpOnly cookie. Scripts use a developer token in the Authorization header. Keep credentials out of links, logs, examples, and public files. A 401 needs valid authentication; a 403 can indicate missing scope, ownership, or access. Read the error detail before choosing a remedy.

what is portable, and what is private

Public tracks, likes, comments, and public playlists use ATProto records. Private playlists remain in plyr.fm’s database. Experimental private tracks use permissioned data on a compatible PDS; supporter-gated tracks use a separate access check. These are distinct capabilities, not interchangeable labels.

Discovery filtering also differs from access control. Adult-audio labels affect where tracks are suggested, while a direct link can still play. Private and supporter-gated audio have access requirements. The moderation table describes each surface.

check the whole workflow

A useful read-only integration check is:

1. Fetch /llms.txt from the app and follow the OpenAPI link. Check the body and content type, not only a successful status code.
2. Search for a known term and inspect the typed results.
3. Fetch one returned track ID and confirm its identity matches the selection.
4. Produce the track page and inspect its audio URL. If testing audio delivery, fetch only what the test needs and verify the response is audio.
5. For MCP, rediscover tools and run the same search → detail flow. Verify that unauthenticated library reads report the missing authentication clearly.

Do not issue likes, uploads, or play-count writes as a connectivity test. The quickstart contains executable SDK and HTTP examples.

writing an MCP server

The webinar Is Your MCP Server Good? compares several ways to expose the Prefect API, with runnable examples for OpenAPI generation, response trimming, code mode, and a hand-written server. A few practices carry over to plyr.fm integrations:

1. Choose tasks before tools. Write down what someone should accomplish, such as finding audio and inspecting a selection. Give each tool a clear role in that workflow, with enough information to choose the next step.
2. Make inputs and results precise. Include units, bounds, identifiers, access requirements, and what a result establishes. Preserve the distinction between unknown values and empty collections when reducing a response.
3. Inspect the context cost. Measure tool listings and representative responses. Code mode can make initial discovery smaller; include the schemas and results fetched during the task when evaluating the whole interaction.
4. Exercise realistic requests. Run an agent with only the server’s tools. Review its calls, evidence, answer, and handling of missing credentials or unavailable operations. Repeat after changing names, descriptions, or schemas.
5. Check shared behavior automatically. Keep HTTP logic and models in a shared client. Test filters, result fields, permissions, and write payloads across the interfaces that expose them. Keep repeatable checks in pre-commit and CI, and run live checks against the deployed server too.

The webinar scripts estimate token counts from serialized length. Those estimates help compare designs; reviewing completed agent workflows establishes whether people can use the resulting tools successfully.