MCPAPI Reference

API Reference

HTTP endpoints for ONCE MCP. User-scoped endpoints usually require Authorization: Bearer <token>. Large-file upload chunk + complete requests can also use the scoped x-mcp-upload-token returned by prepare_local_file_upload.

Base URL: https://beta.once.app

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

Authentication

OAuth Metadata Discovery

GET/.well-known/oauth-protected-resource

Protected Resource Metadata for MCP OAuth discovery.

GET/.well-known/oauth-authorization-server

OAuth Authorization Server metadata (RFC 8414).

GET/.well-known/openid-configuration

OpenID Connect metadata compatibility endpoint.

OAuth Endpoints

GET/oauth/authorize

Authorization endpoint for MCP client browser sign-in.

POST/oauth/token

Token endpoint for authorization code + PKCE exchange and refresh token grants.

POST/oauth/register

Dynamic client registration endpoint for MCP client interoperability.

Most MCP clients use these automatically after a 401 Unauthorized challenge from /api/mcp.

Uploads

Multipart Upload

POST/api/mcp/upload

Upload cover art or audio via multipart form-data.

Form Fields

FieldTypeDescription
filebinaryThe file to upload
typestringcoverArt or audio

Response

{
  "success": true,
  "fileUrl": "/api/files/cover-art/USER_ID/file.jpg",
  "fileName": "file.jpg",
  "userId": "..."
}

Local Upload Session

For large local files in Claude Code or Cursor, call the prepare_local_file_upload MCP tool first. It returns:

  • session_id
  • upload_token
  • upload_header_name (x-mcp-upload-token)
  • chunk_endpoint
  • complete_endpoint
  • recommended_chunk_bytes
  • max_chunk_bytes

Upload Chunk

POST/api/mcp/upload/chunk

Upload a single chunk using the scoped token returned by prepare_local_file_upload.

Headers

  • x-mcp-upload-token: <upload_token>
  • For raw bytes: x-session-id, x-chunk-index, x-upload-type

Multipart Fields

  • chunk
  • chunkIndex
  • sessionId
  • type

JSON Request

{
  "chunkBase64": "...",
  "chunkIndex": 0,
  "sessionId": "uuid-v4",
  "type": "audio"
}

Raw Bytes Body

Send the chunk as application/octet-stream with the headers listed above.

For large uploads, prefer raw bytes or multipart over JSON base64 to avoid extra payload overhead.

Complete Chunked Upload

POST/api/mcp/upload/complete

Finalize a chunked upload session.

Request

{
  "sessionId": "uuid-v4",
  "fileName": "Track.wav",
  "fileType": "audio/wav",
  "type": "audio"
}

Include x-mcp-upload-token: <upload_token> on the completion request.

Drafts

Save Draft

POST/api/mcp/draft

Persist a draft snapshot before submission.

Request

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

Releases

Submit Release

POST/api/mcp/submit

Submit a release for distribution. Rate limited; check retryAfterSeconds on 429.

Request

{
  "release": {
    "title": "My Release",
    "primary_artist_name": "Artist Name",
    "genre": "Pop",
    "release_date": "2026-02-01",
    "cover_art_file_url": "/api/files/cover-art/USER_ID/cover.jpg"
  },
  "tracks": [
    {
      "title": "My Release",
      "primary_artist_name": "Artist Name",
      "audio_file_url": "/api/files/audio/USER_ID/track.wav",
      "explicit_flag": false,
      "writers": [{ "name": "First Last" }]
    }
  ],
  "releaseId": "optional",
  "conversationId": "optional"
}

List Releases

GET/api/mcp/releases

Get recent releases for the authenticated user.

Query Parameters

ParameterTypeDescription
limitnumberMax results (default 100)

Get Release Metadata

GET/api/mcp/releases/:releaseId/metadata

Get merged metadata for a release.

Get Release Status

GET/api/mcp/releases/:releaseId/status

Get store delivery and aggregate status.

Get Job Status

GET/api/mcp/release-jobs/:releaseId

Get processing job status and errors.

UploadsOverview