MCP Server

ONCE MCP gives your agent a single endpoint for music distribution. Connect once, sign in with your ONCE account, and the agent can upload assets, generate cover art, run AI and rights checks, submit releases, buy credits, and report streaming performance.

Building a backend or app rather than an agent? The same capabilities are available as a conventional HTTP API: see REST API.

Connect

Add the server to your MCP client:

{
  "mcpServers": {
    "once": {
      "url": "https://beta.once.app/api/mcp"
    }
  }
}

If your client asks for a transport, choose Streamable HTTP. Most clients prompt for authentication as soon as they scan the server; complete the browser sign-in and you are done. Client-by-client instructions for ChatGPT, Claude, Cursor, and Cline are on Agent Setup.

You can also open MCP setup from My Account → Quick Actions → Developer, where the MCP Settings page lists recent releases you submitted through MCP.

How a release flows

1. Authenticate. Every JSON-RPC method needs a bearer token. Native MCP clients handle the OAuth challenge automatically.
2. Read the rules. Agents must read mcp://docs/metadata-rules-hitlist (or call get_metadata_rules) right after connecting. It summarizes the metadata policies that the JSON schema cannot express: generic artist names, writers, UPC, AI disclosure, cover songs.
3. Upload or generate assets. upload_file for small local files, upload_file_from_url for public URLs, prepare_local_file_upload for large local files, or generate_cover_art for AI artwork. See Uploads.
4. Run checks (optional). detect_audio_ai returns the AI classification that drives billing; detect_audio_pex_search_acr checks for registry matches above 10%.
5. Submit. submit_release with the payload described in Schema. Credits are debited here: 1 per human song, 2 per AI-detected song.
6. Monitor. get_release_status, get_release_job, and get_release_metadata.
7. Track performance. get_performance_summary and get_release_performance once the release is distributed.

Account tools (get_profile, get_credits, get_pricing, create_credit_checkout_session, get_autoreload, set_autoreload) let the agent check the balance and top up in-session. Every tool’s arguments and responses are in the API Reference.

What the server exposes

Tool and resource lists are static during a session (listChanged: false). If a tool is missing after an update, restart your client or re-add the server. The protocol details, including batches, errors, and the auth challenge, are on Protocol & JSON-RPC; the wider set of machine-readable discovery documents is on Agent Discovery.

Scope and billing

• Supports store selection with release.distribution_store_ids (fetch IDs with get_distribution_stores; null means all supported stores).
• Accepts expanded metadata: label, C/P credits, role credits, lyrics, language, artist localization, and per-artist profile links.
• No validation agent or mastering in the MCP flow.
• Billing is the same as the app and REST API: 1 credit per human song, 2 per AI-detected song, debited from the authenticated account at submission. Requests are tagged with a provenance (MCP by default, AIMD for the AI Music Distribution partner surface) for analytics; it never changes the rate.
• ONCE Insiders get higher rate limits. Connecting never requires a membership.