MCP Clients

ONCE MCP works with any MCP-compatible client. Point your agent to the MCP endpoint and let it handle the entire release flow—authentication, uploads, submission, and status tracking.

Quick Setup

Add this to your MCP client configuration:

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

That’s it. The agent can now discover all available tools and resources automatically.

What the Agent Can Do

Once connected, the agent has full access to:

• Authenticate with your ONCE credentials
• 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.

Recommended Clients

Client Configuration Examples

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

Restart Claude Desktop. Ask it to “list available MCP tools” to verify the connection.

Cline (VS Code)

Open Cline settings and add the MCP server:

{
  "cline.mcpServers": {
    "once": {
      "url": "https://beta.once.app/api/mcp",
      "transport": "http"
    }
  }
}

Cursor

Cursor supports MCP tools. Add to your MCP configuration:

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

Example Conversation

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

“Log in to ONCE with my email user@example.com and password, then upload cover.jpg as cover art and track.wav as audio. Submit a release called ‘My Song’ by ‘Artist Name’ in the Pop genre, releasing on February 1st 2026. The track is not explicit and I wrote it.”

The agent will:

1. Call auth_login to get an access token
2. Call upload_file for cover art and audio
3. Call submit_release with the metadata
4. Return the release ID and status

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

Client Matrix

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