Agent Setup

Plug ONCE into your MCP client and you’re ready to go. Authenticate once, then your client can run discovery and tool calls normally.

Quick Setup

Add this to your MCP client configuration:

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

If your client asks for a transport, choose Streamable HTTP (or just HTTP). That’s it. The agent can discover all available tools and resources after authentication.

What Happens After You Connect

Most clients immediately scan the server:

• tools/list loads the tool catalog
• resources/list shows available docs + schema
• Some clients also fetch the server card at /.well-known/mcp/server-card.json

If a scan or action gets a 401 Unauthorized, click Authenticate / Sign in and complete the browser flow.
Tool/resource lists are static during a session (listChanged: false), so if a tool is missing after an update, restart your client or re-add the server.

Client Configuration

ChatGPT (Developer Mode)

1. Enable Developer Mode under Settings → Apps & Connectors → Advanced settings.
2. Go to Settings → Connectors → Create and paste https://beta.once.app/api/mcp.
3. Give it a name + description, then click Create.
4. In a new chat, click + → More → Developer Mode and add the connector.

ChatGPT will scan tools and resources automatically after you add it. Developer Mode is currently in beta and requires an eligible ChatGPT plan.

Claude (Web)

1. Open Claude → Settings → Connectors → Add custom connector.
2. Paste https://beta.once.app/api/mcp.
3. Finish any auth prompts if Claude shows them during discovery.

You can attach resources (like the schema) from the connector menu once it’s connected.

Claude Desktop (Local Servers Only)

Claude Desktop loads local MCP servers from claude_desktop_config.json. ONCE is a remote HTTP server, so the easiest path is Claude web connectors.
If you still want Desktop, you’ll need a local MCP bridge; see the MCP local-server setup docs for details.

Cline (VS Code)

1. Open the Cline panel → menu (⋮) → MCP Servers.
2. Go to Remote Servers and click Add Server.
3. Use:
   • Server URL: https://beta.once.app/api/mcp
   • Transport: Streamable HTTP

Advanced config uses a JSON file with:

{
  "mcpServers": {
    "once": {
      "url": "https://beta.once.app/api/mcp",
      "type": "streamableHttp"
    }
  }
}

Cursor

Create .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

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

Example Workflow

Once configured, you can simply tell the agent what you want:

“Connect to ONCE MCP, authenticate, upload cover.jpg as cover art and track.wav as audio, then submit a release called ‘My Song’ by ‘Artist Name’ in the Pop genre for February 1st 2026. The track is not explicit and I wrote it.”

The agent will:

1. Load tools + resources (tools/list, resources/list)
2. Trigger MCP sign-in and store the bearer token
3. Upload small assets directly, or use prepare_local_file_upload for large local files
4. Call submit_release with the metadata
5. Return the release ID and status

Step-by-Step Breakdown

0. Discover Tools + Resources (After Authentication)

Most clients do this for you after sign-in, but here’s what it looks like:

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "resources/read",
  "params": {
    "uri": "mcp://schemas/release-required"
  }
}

Include Authorization: Bearer <token> on discovery calls.

1. Authenticate

Most MCP clients handle this automatically after a 401 challenge from ONCE.

There is no separate in-chat login step for native MCP clients. When Claude, Cursor, or another MCP client shows Authenticate / Sign in, complete the browser flow and then continue using tools normally. Once that flow finishes, the client usually attaches auth automatically, so your tool calls do not need an access_token argument.

2. Upload (or Generate) Assets

The agent uploads files using the appropriate method, or skips the upload entirely by generating AI cover art:

Each upload (or generation) returns a fileUrl to use in the submission.

Generating Cover Art

{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "tools/call",
  "params": {
    "name": "generate_cover_art",
    "arguments": {
      "prompt": "Lo-fi vinyl in a sunset cafe, warm pastels, 70s poster art"
    }
  }
}

Response (the fileUrl is already cropped to square 3000x3000 PNG and stored in the user’s bucket):

{
  "fileUrl": "/api/files/cover-art/USER_ID/<uuid>.png",
  "bucket": "cover-art",
  "key": "USER_ID/<uuid>.png",
  "fileName": "<uuid>.png",
  "prompt": "Lo-fi vinyl in a sunset cafe, warm pastels, 70s poster art",
  "model": "gemini-3.1-flash-image-preview",
  "modelVariant": "nano_banana_2",
  "imageSize": "1K",
  "aspectRatio": "1:1",
  "edited": false,
  "rateLimit": { "remaining": 4 }
}

Pass that fileUrl straight into release.cover_art_file_url when you call submit_release. Rate limited per user under cover_art_generate (5 requests / 2 min by default).

Editing a Previous Generation

To iterate on artwork — the same flow as the in-app cover art generator — pass the prior fileUrl (or raw base64) and a delta prompt:

{
  "jsonrpc": "2.0",
  "id": 12,
  "method": "tools/call",
  "params": {
    "name": "generate_cover_art",
    "arguments": {
      "prompt": "Make the sky more dramatic and add neon signage in the window",
      "baseFileUrl": "/api/files/cover-art/USER_ID/<previous-uuid>.png"
    }
  }
}

The response will set "edited": true and return a fresh fileUrl with the refined image. baseFileUrl must belong to the authenticated user and live in the cover-art bucket; use baseImageBase64 if you have the bytes locally (e.g. from returnBase64: true on the prior call).

3. (Optional) Run AI Detection

After audio uploads, you can ask the agent to run the Vobile/Pex AI Song Detector and surface the result before submitting:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "detect_audio_ai",
    "arguments": {
      "fileUrl": "/api/files/audio/USER_ID/track.wav"
    }
  }
}

The response includes the predicted model (e.g. Suno, Udio) and confidence scores:

{
  "status": "ok",
  "containsAi": true,
  "aiScore": 0.93,
  "predictedModel": "Suno",
  "predictedModelScore": 0.81,
  "provider": "pex",
  "model": "ai-song-detector",
  "cached": false
}

Detection results are cached per file, so repeat calls with the same fileUrl are cheap.

4. Submit Release

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "submit_release",
    "arguments": {
      "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" }]
        }
      ]
    }
  }
}

5. Monitor Status

Poll these tools to track processing:

• get_release_status — Store delivery status
• get_release_job — Processing job status
• get_release_metadata — Current metadata state

Account Tools

After authentication, the agent can pull the user’s profile and credit balance whenever it needs them:

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": { "name": "get_profile", "arguments": {} }
}

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "get_credits",
    "arguments": { "transactionLimit": 5 }
  }
}

get_profile returns id, email, name, signed avatar URL, plus patron and admin flags. get_credits returns the active balance, lifetime aggregates (usedTotal + purchasedTotal), and the most recent transactions.

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_release_status",
    "arguments": {
      "releaseId": "<release-id>"
    }
  }
}

What the Agent Can Do

Once connected, the agent has full access to:

• Authenticate with your ONCE account via browser sign-in flow
• Upload cover art and audio files (base64, URL, or chunked)
• Generate AI cover art with Gemini Nano Banana 2 (1K, available to every authenticated user)
• Detect AI content with Vobile/Pex (model classification + confidence scores)
• Submit releases with all required metadata
• Monitor processing status and store delivery
• Read the user’s profile and credit balance
• Read schema documentation and guides via MCP resources

The agent will read the mcp://docs/agent-guide resource to understand the full workflow and mcp://schemas/release-required for validation rules.

Provenance & Partner Billing

Every MCP request is tagged with a provenance value so ONCE knows which surface initiated it:

Billing is 1 credit per song by default. AIMD submissions are billed at 2 credits per AI-detected song (everything else stays at 1). The provenance is stored on the release row and surfaced in the admin AI dashboard.

Best Practices

• Let discovery finish — Wait for tools/list + resources/list to load before asking for actions
• Read resources early — Pull mcp://docs/agent-guide and mcp://schemas/release-required before building payloads
• Pick the right upload path — Use upload_file_from_url for big hosted files and prepare_local_file_upload for large local files in Claude Code / Cursor
• Save drafts — Use upsert_release_snapshot if you’re collecting metadata over multiple turns
• Handle rate limits — If you use the HTTP submit endpoint and get a 429, retry after retryAfterSeconds

Discovery Endpoints

Tips

• Let the agent read resources first — The agent guide (mcp://docs/agent-guide) contains the full workflow and best practices
• Single command releases — Give all the info upfront and let the agent handle the sequence
• Check status — Ask the agent to call get_release_status to track delivery progress
• Validation errors — The agent can read mcp://schemas/release-required to understand what fields are needed
• Refresh if tools look stale — Tool/resource lists are static per session; restart or re-add the server

Client Compatibility

MCP client support evolves quickly. For the latest compatibility information, see the official MCP client list.

Access Notes

• Credits apply — MCP submissions debit credits from your ONCE balance
• No patron requirement for setup — Any MCP client can connect and authenticate
• Authentication for MCP — You need a ONCE account for discovery and submissions