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’s the same API keys used elsewhere in the Royalti API, so there’s no separate credential to manage.

​
Royalti MCP Server

The MCP endpoint sits in front of the Royalti API and spans catalog, analytics, royalty, and billing 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 “What’s my current royalty due?”
The endpoint is https://api.royalti.io/ai/mcp — a single Streamable HTTP endpoint. There’s no separate MCP host or stdio bridge to install.

​
Prerequisites

  • A Royalti workspace account with an active subscription
  • An MCP-compatible AI client (Claude.ai, Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, etc.)

​
Connect Your AI Client

Most modern MCP clients handle authentication automatically — you just point them at the endpoint URL. If your client doesn’t support that, use the manual API key fallback below. Clients that implement the MCP authorization spec — including Claude.ai — connect with no key-pasting at all. Just add the endpoint URL:
Here’s what happens behind the scenes:
1

Client hits the endpoint unauthenticated

The client’s first request gets a 401 response carrying a WWW-Authenticate: Bearer challenge that points to Royalti’s protected-resource metadata.
2

Client discovers the authorization server

It fetches https://api.royalti.io/.well-known/oauth-protected-resource and https://api.royalti.io/.well-known/oauth-authorization-server to learn the authorization, token, and registration endpoints.
3

Client registers itself

If it doesn’t already have a client ID, it self-registers via POST /oauth/register (RFC 7591) — no manual setup required.
4

You approve access

You’re sent to a consent screen in your browser to sign in and approve the requested scopes. Once approved, the client holds a token scoped to what you allowed.
Reconnecting later reuses the same authorization — you won’t be asked to approve again unless the client requests new scopes or you revoke access.

​
Manual API key (fallback)

If your client doesn’t support MCP’s automatic authorization flow, connect with an API key as a Bearer token instead.
1

Generate a key

Log in to Royalti.io, go to Settings → API Keys, click Generate New Key, and choose a User Key (RUAK_) for personal use or a Workspace Key (RWAK_) for workspace-wide access.
2

Copy the key

Copy it immediately — you won’t be able to view it again after leaving the page.
3

Add it to your client config

Set it as an Authorization: Bearer header, not a URL parameter — the endpoint doesn’t accept a key in the query string.
Replace RUAK_your_key_here with your actual key (RUAK_ or RWAK_), then restart your client. Configuration file locations vary:
Save the file and fully quit and reopen Claude Desktop (don’t just minimize).
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.

​
Which key type should I use?

​
Multiple workspaces

Configure more than one server entry — one per key — to switch between workspaces:
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 the URL is exactly https://api.royalti.io/ai/mcp with no trailing slash
  • If using a manual key, confirm it’s passed as an Authorization: Bearer header, not a URL query parameter
“Authentication failed”
  • Confirm your key starts with RWAK_ or RUAK_ with no extra spaces or quotes
  • Confirm the key hasn’t been revoked in Settings → API Keys
  • If you approved access via the automatic flow, try revoking and reconnecting to get a fresh token
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