MCP Server

ONCE MCP gives your agent a single endpoint for release submission. Connect once, authenticate with your ONCE account, and you’re ready to upload assets and submit releases.

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

Getting Started

The fastest way to start is connecting an MCP client:

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

Most clients will prompt for authentication as soon as they scan MCP methods. See Agent Setup for full configuration examples. You can also open MCP setup from My Account → Quick Actions → Developer, where the MCP section (or the standalone MCP Settings page) includes recent releases you submitted through MCP.

How Tools + Resources Load

Most MCP clients do a quick scan as soon as you add the server:

• initialize
• tools/list
• resources/list
• Sometimes GET /.well-known/mcp/server-card.json

If the server responds with 401 Unauthorized, your MCP client should show an Authenticate / Sign in action. Complete that flow in the browser, then retry.
Tool/resource lists are static during a session (listChanged: false in the server card). If you don’t see new items after an update, restart your client or remove/re-add the server to force a refresh.

Key Features

• Native auth-first flow, Discovery and actions are available right after sign-in
• Native sign-in flow, MCP clients can trigger browser authentication through OAuth challenge responses
• Account-linked usage, MCP submissions debit credits from your ONCE balance
• Full workflow support, Upload, submit, and monitor releases entirely through the agent

Current Scope

• Supports DSP selection with release.distribution_store_ids
• Accepts expanded release and track metadata including label, C/P credits, role credits, lyrics, language, and artist localization
• No validation agent or mastering in the MCP flow

Workflow

1. Connect: Point your MCP client to https://beta.once.app/api/mcp
2. Authenticate: Complete the MCP client sign-in flow (OAuth).
3. Discover: Let the client load tools/list + resources/list
4. Upload (or generate) assets: Use upload_file for small local files, upload_file_from_url for public URLs, prepare_local_file_upload for large local files in Claude Code / Cursor, or generate_cover_art to create AI album art on the fly
5. (Optional) Run detection checks: Call detect_audio_ai to surface the Vobile/Pex AI classification (predicted model + confidence) for each audio file, and detect_audio_pex_search_acr to check a track against the Pex Search / Identify Music registry for possible infringement matches
6. Submit release: Call submit_release with metadata, then poll status endpoints
7. (After distribution) Track performance: Call get_performance_summary for catalog-wide streams and get_release_performance for a single release (with includeTracks for per-song detail)

Account Tools

Once authenticated, the agent can also fetch account state on demand:

• get_profile: id, email, name, signed avatar URL, patron + admin flags
• get_credits: current balance, lifetime aggregates, recent transactions
• create_credit_checkout_session: buy credits via Stripe Checkout ($1/credit); hosted mode returns a payable url so agents can top up in-session
• get_performance_summary / get_release_performance: streaming analytics (streams, trend, top stores, top releases, per-track breakdown)

Provenance & Billing

Every MCP request is tagged with the surface that initiated it, MCP (default) or AIMD (app.aimusicdistributor.com). Billing is the same regardless of provenance: 1 credit per human song, 2 credits per AI-detected song. The provenance is persisted on the release and surfaced in the admin AI dashboard for analytics.

Discovery

MCP Resources

ONCE MCP exposes read-only resources via resources/list and resources/read:

• mcp://docs/metadata-rules-hitlist: Required on connect: quick-hit metadata policies agents must read and pass on to users (markdown). Same content as the get_metadata_rules tool.
• mcp://docs/agent-guide: Protocol guide (markdown)
• mcp://schemas/release-required: Required fields and example payload (JSON)

Use the get_distribution_stores tool to fetch supported DSP store IDs. Pass a non-empty array as release.distribution_store_ids to select DSPs, or null to distribute to all supported stores.

Authentication

All MCP JSON-RPC methods require authentication and trigger an OAuth sign-in challenge when needed.
Native MCP clients attach the bearer token automatically, so tool calls usually do not need an access_token argument.