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

Agents must read the metadata rules hitlist right after authentication, either resources/read on mcp://docs/metadata-rules-hitlist or get_metadata_rules. That document summarizes the most important ONCE metadata policies (generic artist names, writers, UPC, AI disclosure, cover songs, etc.) so the agent can guide the user correctly before submit.

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. Read the metadata rules hitlist first, then the schema:

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "resources/read",
  "params": {
    "uri": "mcp://docs/metadata-rules-hitlist"
  }
}

Or call get_metadata_rules (returns { "markdown": "..." }).

{
  "jsonrpc": "2.0",
  "id": 1,
  "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

The example below shows the backward-compatible MVP shape. New clients should read mcp://schemas/release-required and include DSP selection, label, C/P copyright credits, track_type, and role credits when available.

{
  "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" }]
        }
      ],
      "tokenOffset": false
    }
  }
}

Token Offset Opt-In

The optional Token Offset add-on defaults to off and never blocks a submission. In an interactive chat, the agent can offer it before calling submit_release:

“Want to add a $1 (1 credit) Token Offset to offset the AI environmental cost of this release? Funded via tokenoffset.com, totally optional.”

When running autonomously, the agent simply submits with tokenOffset: false unless your instructions opt in. If accepted, pass tokenOffset: true (top-level argument, not inside release). The opt-in works the same on every MCP surface (Non-AIMD and AIMD) and:

• Adds a flat +1 credit ($1) regardless of track count or AI surcharge.
• Is debited as a separate credit_transactions row with ref=token_offset:<release_id>, so it appears as its own line in the user’s credit history.
• Is recorded in the release_token_offsets table for admin offset-revenue reporting, with a paid_with_granted snapshot so granted/referral credits don’t inflate revenue.

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

6. Track Performance

Once a release is distributed and accruing plays, report streaming analytics:

• get_performance_summary: catalog-wide streams, daily trend, top stores, and top releases over a window (defaults to the trailing 30 days).
• get_release_performance: per-release streams, daily trend, and per-store breakdown for one releaseId. Pass includeTracks: true for a per-song breakdown, or distributorId to focus on a single store (-1300 = YouTube Music).

{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "get_release_performance",
    "arguments": { "releaseId": "uuid", "includeTracks": true }
  }
}

Figures match the in-app dashboard; newly distributed releases may read zero until DSPs report and the cache backfills. See API Reference → Performance Analytics.

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.

Buying Credits via MCP

Agents can purchase credits without leaving the MCP session. Pricing is $1 per credit (1 credit per human track, 2 per AI track, +1 for Token Offset). The recommended flow:

1. get_credits to check the balance against the projected submission cost.
2. If short, call create_credit_checkout_session with uiMode: "hosted":

{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "create_credit_checkout_session",
    "arguments": { "credits": 5, "uiMode": "hosted" }
  }
}

3. The response contains a Stripe-hosted Checkout url. Agents with payment capability (for example, agentic-commerce flows where you’ve provisioned a payment method) can complete it directly; otherwise the agent shares the link and you pay it — that’s the only step that can require a human.
4. Credits land automatically via webhook once payment succeeds; the agent polls get_credits and continues to submit_release.

See the API Reference for the full request/response shapes.

{
  "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
• Buy credits via Stripe Checkout (create_credit_checkout_session with hosted mode)
• Read schema documentation and guides via MCP resources

The agent will read mcp://docs/metadata-rules-hitlist (required), then mcp://docs/agent-guide for the full workflow and mcp://schemas/release-required for required fields.

Provenance & Partner Billing

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

Billing is 1 credit per human song and 2 credits per AI-detected song on every surface. Provenance (MCP vs AIMD) is recorded on the release row and surfaced in the admin AI dashboard for analytics, it doesn’t change the rate.

Best Practices

• Let discovery finish: Wait for tools/list + resources/list to load before asking for actions
• Read resources early: Pull mcp://docs/metadata-rules-hitlist first, then 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: Start with mcp://docs/metadata-rules-hitlist, then the agent guide (mcp://docs/agent-guide) for the full workflow
• 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; agents can top up in-session with create_credit_checkout_session
• No patron requirement for setup: Any MCP client can connect and authenticate
• Authentication for MCP: You need a ONCE account for discovery and submissions