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.

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"
}

Rate limited. On 429 response, check retryAfterSeconds.

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

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.

Protocol & JSON-RPCUploads