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 Assets

The agent uploads files using the appropriate method:

Each upload returns a fileUrl to use in the submission.

3. 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" }]
        }
      ]
    }
  }
}

4. 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

{
  "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)
• Submit releases with all required metadata
• Monitor processing status and store delivery
• 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.

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