Skip to main content
Royalti.io exposes a Model Context Protocol (MCP) endpoint that lets MCP-compatible AI assistants — Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, and other MCP clients — read and act on your workspace data through natural language. It authenticates with the same API keys used elsewhere in the Royalti API, so there’s no separate credential to manage.

​
Royalti MCP Server

The MCP server sits in front of the Royalti API and spans catalog, analytics, royalty, billing, DDEX, and file-processing data. Once connected, you ask your AI assistant to do the work instead of writing API calls by hand — for example, “Show me my top 5 artists by revenue this quarter” or “Upload the royalty file in my Downloads folder.”

​
Prerequisites

  • A Royalti workspace account with an active subscription
  • An API key — a Workspace Key (RWAK_) or a User Key (RUAK_)
  • An MCP-compatible AI client

​
Step 1: Get an API Key

​
Which key type should I use?

Key typePrefixBest for
User KeyRUAK_Recommended for most MCP setups. Scoped to your personal user account — least-privilege access. Use this unless you specifically need workspace-wide operations.
Workspace KeyRWAK_Workspace-wide access. Use for automations or integrations that need to operate on behalf of the whole workspace rather than a single user.
1

Log in and open API Keys

Log in to Royalti.io and go to Settings → API Keys.
2

Generate a key

Click Generate New Key, then select User Key (RUAK_) for personal use or Workspace Key (RWAK_) for workspace-wide integrations.
3

Copy the key

Copy the key immediately — you won’t be able to view it again after leaving the page.
Never share your API key in chat or commit it to version control. If a key is exposed, revoke it immediately and generate a new one.

​
Step 2: Connect Your AI Client

There are two ways to connect: the hosted endpoint (simplest) or a local stdio bridge (keeps your key off the wire).

​
Hosted endpoint

Add the Royalti MCP server to your client’s configuration with your API key in the URL: 
{
  "mcpServers": {
    "royalti": {
      "url": "https://mcp.royalti.io?api_key=RUAK_your_key_here"
    }
  }
}
Replace RUAK_your_key_here with your actual key (RUAK_ or RWAK_), then restart your client. Configuration file locations vary by client:
PlatformLocation
macOS~/Library/Application Support/Claude/claude_desktop_config.json
Windows%APPDATA%\Claude\claude_desktop_config.json
Save the file and fully quit and reopen Claude Desktop (don’t just minimize).
The ?api_key= query-string form works and is supported, but it puts your key in the URL, where it can appear in proxy logs. If you’d rather keep the key off the wire entirely, use the local stdio bridge below.
The stdio bridge keeps your key in a local environment variable — it travels only as an HTTPS request header, never in a URL. It’s published to npm as royalti-mcp-bridge and runs via npx, so there’s no install or build step (Node.js 18+ required). 
{
  "mcpServers": {
    "royalti": {
      "command": "npx",
      "args": ["-y", "royalti-mcp-bridge"],
      "env": {
        "ROYALTI_API_KEY": "RUAK_your_key_here"
      }
    }
  }
}
Replace RUAK_your_key_here with your actual key (RUAK_ or RWAK_). The bridge relays MCP calls to Royalti’s hosted MCP service over HTTPS with your key in the Authorization header, so you always get the same tool surface as the hosted endpoint without the key ever appearing in a URL.

​
Multiple workspaces

Configure more than one server entry to switch between workspaces: 
{
  "mcpServers": {
    "royalti-label": {
      "url": "https://mcp.royalti.io?api_key=RWAK_label_workspace_key"
    },
    "royalti-personal": {
      "url": "https://mcp.royalti.io?api_key=RUAK_personal_user_key"
    }
  }
}
Your AI assistant will ask which configured server to use when running a command.

​
Security Best Practices

  • Prefer a User Key (RUAK_) for personal setups — it limits any unintended write operation to your own context. Reserve Workspace Keys (RWAK_) for automations and workspace-wide integrations.
  • Rotate keys periodically. Generate a new key, update your client configuration, verify the connection, then revoke the old key in Settings → API Keys.
  • Never share keys in chat or commit them to version control. Use environment variables or a secrets manager for automations.

​
Troubleshooting

“Server not found” or “Connection refused”
  • Confirm your key starts with RWAK_ or RUAK_ with no extra spaces or quotes
  • Confirm the URL is exactly https://mcp.royalti.io?api_key=... with no trailing slash
  • Try loading https://mcp.royalti.io directly in a browser to confirm connectivity
“Authentication failed”
  • Confirm the key hasn’t been revoked in Settings → API Keys
  • Generate a new key and update your configuration
Configuration not picked up
  • Validate your config file’s JSON syntax
  • Fully quit and reopen your AI client (don’t just minimize)
  • Confirm the server entry is named royalti (lowercase)

​
Support