MCPOverview

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.

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 your ONCE dashboard at MCP Settings, which 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

  • Releases are distributed to all stores (store selection coming soon)
  • Accepts a subset of metadata fields compared to the ONCE app
  • 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 AI detection — Call detect_audio_ai to surface the Vobile/Pex AI classification (predicted model + confidence) for each audio file
  6. Submit release — Call submit_release with metadata, then poll status endpoints

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

Provenance & Billing

Every MCP request is tagged with the surface that initiated it — MCP (default) or AIMD (app.aimusicdistributor.com). Submissions tagged AIMD are billed at 2 credits per AI-detected song; everything else stays at 1 credit per song. The provenance is persisted on the release and surfaced in the admin AI dashboard.

Discovery

ResourceEndpoint
MCP endpointPOST /api/mcp
Server cardGET /.well-known/mcp/server-card.json
Docs endpointGET /api/mcp/docs

MCP Resources

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

  • mcp://docs/agent-guide — Protocol guide (markdown)
  • mcp://schemas/release-required — Required fields and example payload (JSON)

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.

FAQAgent Setup