Setting Up the Royalti MCP Server

Connect your AI assistant to your Royalti workspace in about 5 minutes. No installation required—just add your API key and start querying your royalty data in natural language.

Prerequisites

Before starting, make sure you have:

• Royalti workspace account with active subscription
• Workspace API Key (RWAK) from your Royalti settings
• AI client of your choice (Claude Desktop, Claude Code, VS Code, Cursor, Windsurf, ChatGPT, or Gemini CLI)

That's it. No Node.js, no terminal commands, no building from source.

Step 1: Get Your API Key

Generate a Workspace API Key

1. Log in to Royalti.io
2. Go to Settings → API Keys
3. Click Generate New Key
4. Select Workspace Key (starts with RWAK_)
5. Copy the key immediately—you won't see it again

Example key format: RWAK_7dnhPNJ8O5CXKJN3wZBz3E4yr

Step 2: Configure Your AI Client

Choose your preferred AI client below and follow the setup instructions.

Claude Desktop

Claude Desktop is Anthropic's official desktop application for Claude.

Step 1: Find your configuration file:

Step 2: Add the Royalti MCP server:

1{
2  "mcpServers": {
3    "royalti": {
4      "type": "http",
5      "url": "https://mcp.royalti.io?api_key=RWAK_your_api_key_here"
6    }
7  }
8}
Copy

Step 3: Replace RWAK_your_api_key_here with your actual API key.

Step 4: Save the file and restart Claude Desktop completely (quit and reopen, don’t just minimize).

Claude Code (CLI)

Claude Code is Anthropic’s command-line interface for Claude, ideal for developers.

Option 1: CLI command (recommended)

Run the following command in your terminal:

1claude mcp add --transport http royalti "https://mcp.royalti.io?api_key=RWAK_your_api_key_here"
Copy

Replace RWAK_your_api_key_here with your actual API key. Restart Claude Code or start a new session.

Option 2: Manual configuration

Create or edit ~/.claude.json (or .mcp.json in your project root):

1{
2  "mcpServers": {
3    "royalti": {
4      "type": "http",
5      "url": "https://mcp.royalti.io?api_key=RWAK_your_api_key_here"
6    }
7  }
8}
Copy

Replace RWAK_your_api_key_here with your actual API key and restart Claude Code.

VS Code

VS Code supports MCP through GitHub Copilot. No additional extensions required.

Step 1: Create or edit .vscode/mcp.json in your project root:

1{
2  "servers": {
3    "royalti": {
4      "type": "http",
5      "url": "https://mcp.royalti.io?api_key=RWAK_your_api_key_here"
6    }
7  }
8}
Copy

Step 2: Replace RWAK_your_api_key_here with your actual API key.

Step 3: Reload your editor window.

Global configuration: For system-wide access across all projects, add to ~/.vscode/mcp.json.

Cursor

Cursor supports MCP servers natively through its settings.

Step 1: Create or edit .cursor/mcp.json in your project root:

1{
2  "mcpServers": {
3    "royalti": {
4      "url": "https://mcp.royalti.io?api_key=RWAK_your_api_key_here"
5    }
6  }
7}
Copy

Step 2: Replace RWAK_your_api_key_here with your actual API key.

Step 3: Reload your editor window.

Global configuration: For system-wide access, add to ~/.cursor/mcp.json.

Windsurf

Windsurf supports MCP through its Cascade AI integration.

Step 1: Create or edit your Windsurf MCP config file:

Step 2: Add the Royalti MCP server:

1{
2  "mcpServers": {
3    "royalti": {
4      "serverUrl": "https://mcp.royalti.io?api_key=RWAK_your_api_key_here"
5    }
6  }
7}
Copy

Step 3: Replace RWAK_your_api_key_here with your actual API key.

Step 4: Restart Windsurf for changes to take effect.

ChatGPT

ChatGPT supports MCP through Developer Mode in the desktop application. Available on Pro, Plus, Business, Enterprise, and Education plans (beta).

Step 1: Download and install ChatGPT Desktop for macOS or Windows.

Step 2: Go to Settings → Connectors → Advanced → Developer Mode.

Step 3: Click Create to add a new connector.

Step 4: Fill in the connector details:

• Name: Royalti
• URL: https://mcp.royalti.io?api_key=RWAK_your_api_key_here

Step 5: Replace RWAK_your_api_key_here with your actual API key.

Step 6: Click Refresh after adding, then test the connection.

Gemini CLI

Gemini CLI is Google’s open-source AI agent for your terminal.

Step 1: Install Gemini CLI if you haven’t already:

1npm install -g @google/gemini-cli
Copy

Step 2: Create or edit your settings file:

Step 3: Add the Royalti MCP server:

1{
2  "mcpServers": {
3    "royalti": {
4      "httpUrl": "https://mcp.royalti.io?api_key=RWAK_your_api_key_here"
5    }
6  }
7}
Copy

Step 4: Replace RWAK_your_api_key_here with your actual API key.

Step 5: Restart Gemini CLI or start a new session.

Step 3: Test the Connection

Once configured, verify the connection is working.

Health Check

Ask your AI assistant:

Check Royalti server health

Expected response:

1{
2  "status": "healthy",
3  "api_connected": true,
4  "workspace": "Your Workspace Name"
5}
Copy

List Available Tools

Ask:

What Royalti tools are available?

You should see tools like:

• get_analytics_summary
• upload_royalty_file
• query_artist_analytics
• search_artists
• health_check

Run Your First Query

Try a real query:

Show me my analytics summary

Step 4: Your First Commands

Now let's use the MCP server for real work.

Get Analytics Summary

Try: Get analytics summary for my workspace

Expected output:

• Total revenue across all platforms
• Revenue breakdown by source (Spotify, Apple, YouTube)
• Revenue by artist
• Payment status

Search Your Catalog

Try: Search for artist "Artist Name"

Expected output:

• Artist profile information
• Associated products and releases
• Revenue summary

Query Specific Data

Try: Show me top earning tracks in the last 30 days

Expected output:

• Track-level revenue breakdown
• Platform distribution
• Streaming counts and earnings

Advanced Configuration

Multiple Workspaces

If you manage multiple Royalti workspaces, configure each with a unique name:

1{
2  "mcpServers": {
3    "royalti-label": {
4      "type": "http",
5      "url": "https://mcp.royalti.io?api_key=RWAK_label_workspace_key"
6    },
7    "royalti-personal": {
8      "type": "http",
9      "url": "https://mcp.royalti.io?api_key=RWAK_personal_workspace_key"
10    }
11  }
12}
Copy

Your AI assistant will ask which workspace to use when running commands.

Rate Limiting

The Royalti MCP server includes built-in rate limiting to prevent accidental overuse:

• Default: 100 requests per minute
• Batch operations: Automatically chunked to respect limits

If you hit rate limits, wait a moment and try again.

Troubleshooting

"Server not found" or "Connection refused"

1. Check your API key format:
2. • Must start with RWAK_
   • No extra spaces or quotes around the key
2. Verify the URL:
3. • Should be exactly https://mcp.royalti.io?api_key=RWAK_xxx
   • No trailing slashes
3. Check your internet connection:
4. • Try accessing https://mcp.royalti.io in your browser

"Authentication failed"

1. Verify your API key is valid:
2. • Log in to Royalti → Settings → API Keys
   • Ensure the key hasn't been revoked
2. Check key type:
3. • Must be a Workspace key (RWAK_), not a User key (RUAK_)
3. Try regenerating:
4. • Create a new API key and update your config

"Tool not available"

1. Validate your configuration file:
2. • Paste into JSONLint to check for syntax errors
   • Look for missing commas, quotes, or brackets
2. Restart your AI client:
3. • Fully quit and reopen (don't just minimize)
3. Check MCP server name:
4. • Must be royalti (lowercase) in your config

"Timeout" errors

1. Check your network:
2. • Corporate firewalls may block the connection
   • Try from a different network
2. Large queries:
3. • Break up large date ranges into smaller chunks
   • Query specific artists instead of entire catalog

Security Best Practices

Use Workspace Keys

Workspace API Keys (RWAK_) are designed for integrations:

• Grant workspace-level permissions only
• Can be restricted to specific operations
• Don't expose personal user data

Rotate Keys Regularly

Set a calendar reminder to rotate API keys every 90 days:

1. Create a new workspace API key in Royalti
2. Update your config file with the new key
3. Restart your AI client
4. Verify the connection works
5. Revoke the old key in Royalti Settings

Never Share Keys

• Don't paste API keys into chat conversations
• Don't commit config files with keys to version control
• Use environment variables or secrets managers in production

Related Resources

• Royalti MCP Server Documentation
• Model Context Protocol Specification
• Claude Desktop MCP Guide

Need more help? Contact support at [email protected] or use the chat widget in the bottom right corner.