MCPHTTP Endpoints

HTTP Endpoints

REST-style endpoints available alongside JSON-RPC. User-scoped endpoints usually require Authorization: Bearer <token>. Large-file chunk uploads can also use the scoped x-mcp-upload-token returned by prepare_local_file_upload.

Provenance

Every request to /api/mcp is tagged with a provenance: an identifier for which surface initiated it. ONCE auto-detects:

  • AIMD: the request Origin / Referer matches app.aimusicdistributor.com, OR the JSON-RPC arguments include "provenance": "AIMD" (used for server-to-server calls).
  • MCP: every other authenticated MCP client.

Billing is the same on every surface: 1 credit per human song, 2 credits per AI-detected song. Provenance (MCP vs AIMD) is recorded on the release row (releases.mcp_provenance) for analytics in the admin AI dashboard, it does not change the rate.

Authentication

OAuth metadata discovery (no auth required)

  • GET /.well-known/oauth-protected-resource
  • GET /.well-known/oauth-protected-resource/api/mcp
  • GET /.well-known/oauth-authorization-server
  • GET /.well-known/openid-configuration

OAuth authorization + token

  • GET /oauth/authorize
  • POST /oauth/token
  • POST /oauth/register

Most MCP clients use these automatically when they receive a 401 challenge from /api/mcp.

Upload

POST /api/mcp/upload (requires auth)

Multipart form-data with fields:

FieldDescription
fileBinary file data
typecoverArt or audio

Returns fileUrl for use in submission payloads.

Large local files in Claude Code / Cursor

  1. Call the prepare_local_file_upload MCP tool.
  2. Upload chunks to POST /api/mcp/upload/chunk with x-mcp-upload-token.
  3. Finish with POST /api/mcp/upload/complete using the same scoped token.

Draft Snapshot

POST /api/mcp/draft (requires auth)

Save work-in-progress metadata before final submission.

{
  "releaseId": "optional",
  "conversationId": "optional",
  "mode": "delta",
  "release": { ... },
  "tracks": [ ... ],
  "trackPatches": [ ... ],
  "uploadRequests": [ ... ],
  "status": "collecting"
}

Submit Release

POST /api/mcp/submit (requires auth)

{
  "release": { ... },
  "tracks": [ ... ],
  "releaseId": "optional",
  "conversationId": "optional",
  "tokenOffset": false
}

Rate limited. On 429 response, check retryAfterSeconds.

Note: MCP submissions debit credits from the authenticated ONCE account.

Token Offset (optional): Set tokenOffset: true to add a flat +1 credit ($1) that funds tokenoffset.com to offset the AI environmental cost of the release. Recorded in release_token_offsets and surfaced as a separate credit_transactions row with ref=token_offset:<release_id> so it shows up cleanly in the user’s credit history. Available on every MCP surface (Non-AIMD and AIMD). The agent is expected to offer this opt-in to the user before submitting.

AI Detection

The Vobile/Pex AI Song Detector is exposed as the detect_audio_ai MCP tool, there is no dedicated REST endpoint. After uploading audio, call the tool with the returned fileUrl to read back the detection result (including the predicted-model classification). See API Reference → AI Detection.

Profile, Pricing & Credits

The agent can fetch the authenticated user’s profile, the price list, and the credit balance directly:

  • get_profile MCP tool, returns id, email, name, signed avatar URL, patron + admin flags. Mirrors GET /api/profile.
  • get_pricing MCP tool, returns the full price list: $1/credit, per-song cost (1 credit human / 2 credits AI), the Token Offset add-on, every discounted bulk bundle (with its packageId), and how auto-reload works. No auth-specific data. Mirrors GET /v1/pricing.
  • get_credits MCP tool, returns balance, lifetime aggregates, and recent transactions. Mirrors GET /api/credits.
  • create_credit_checkout_session MCP tool, creates a Stripe Checkout session for buying credits. Pass credits for a custom $1/credit amount or packageId for a discounted bundle. Hosted mode (uiMode: "hosted") returns a payable url; embedded mode returns a clientSecret for web UIs. Pass savePaymentMethod: true to keep the card for auto-reload.

See API Reference → Profile & Credits.

Auto-reload

Auto-reload tops the balance back up off-session whenever it falls to the threshold (0 by default), so a release never stalls mid-submission.

  • get_autoreload MCP tool, returns the current config (enabled, reload amount, threshold, saved card, last status). Mirrors GET /v1/me/autoreload.
  • set_autoreload MCP tool, enables/disables/reconfigures it. Choose the reload amount with packageId (a bundle) or a custom quantity; enabling needs a saved card (paymentMethodId, or omit it to reuse the most recent saved card). Mirrors POST /v1/me/autoreload.

To set it up end-to-end, call create_credit_checkout_session with savePaymentMethod: true, then set_autoreload with { "enabled": true, "packageId": "credits_100" }.

List Releases

GET /api/mcp/releases?limit=100 (requires auth)

Returns the most recent releases for the authenticated user.

Release Metadata

GET /api/mcp/releases/:id/metadata (requires auth)

Returns merged metadata for a release (draft snapshot or latest merged data).

Release Status

GET /api/mcp/releases/:id/status (requires auth)

Returns store and aggregate status information.

Job Status

GET /api/mcp/release-jobs/:id (requires auth)

Returns job processing status and error information.

Performance Analytics

Streaming performance is exposed as two read-only MCP tools (no dedicated REST endpoint). Both default to the trailing 30 days and accept an optional fromDate/toDate window (YYYY-MM-DD). Data is scoped to the authenticated user’s releases.

  • get_performance_summary MCP tool — catalog-wide totals, daily time series, top stores, and top releases.
  • get_release_performance MCP tool — per-release totals, daily time series, per-store breakdown, and (with includeTracks: true) per-track streams.

See API Reference → Performance Analytics.

Protocol & JSON-RPCUploads