> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.royalti.io/llms.txt
> Use this file to discover all available pages before exploring further.

# AI & MCP Integration

> Connect AI assistants to your Royalti workspace through the hosted MCP endpoint or a local stdio bridge

Royalti.io exposes a [Model Context Protocol](https://modelcontextprotocol.io) (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 type          | Prefix  | Best for                                                                                                                                                             |
| ----------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **User Key**      | `RUAK_` | **Recommended for most MCP setups.** Scoped to your personal user account — least-privilege access. Use this unless you specifically need workspace-wide operations. |
| **Workspace Key** | `RWAK_` | Workspace-wide access. Use for automations or integrations that need to operate on behalf of the whole workspace rather than a single user.                          |

<Steps>
  <Step title="Log in and open API Keys">
    Log in to [Royalti.io](https://royalti.io) and go to **Settings → API Keys**.
  </Step>

  <Step title="Generate a key">
    Click **Generate New Key**, then select **User Key** (`RUAK_`) for personal use or **Workspace Key** (`RWAK_`) for workspace-wide integrations.
  </Step>

  <Step title="Copy the key">
    Copy the key immediately — you won't be able to view it again after leaving the page.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

## 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:

```json theme={null}
{
  "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:

<Tabs>
  <Tab title="Claude Desktop">
    | Platform | Location                                                          |
    | -------- | ----------------------------------------------------------------- |
    | 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).
  </Tab>

  <Tab title="Claude Code">
    Edit `~/.claude/settings.json` and add the `mcpServers` block above, then restart Claude Code or start a new session.
  </Tab>

  <Tab title="VS Code / Cursor / Windsurf">
    Create or edit `.vscode/mcp.json` in your project root (or the equivalent `.cursor/mcp.json` / `.windsurf/mcp.json` for a global config), using `servers` instead of `mcpServers`:

    ```json theme={null}
    {
      "servers": {
        "royalti": {
          "url": "https://mcp.royalti.io?api_key=RUAK_your_key_here"
        }
      }
    }
    ```

    Reload the editor window afterward.
  </Tab>
</Tabs>

<Note>
  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.
</Note>

### Local stdio bridge (recommended for developers)

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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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)

## Related Resources

* **[Authentication Guide](/introduction/authentication)** — API key types and token management in depth
* **[API Reference](/api-reference)** — Browse all available endpoints
* **[Model Context Protocol Specification](https://modelcontextprotocol.io)**

## Support

* **Help Center**: [royalti.io/help](https://royalti.io/help)
* **Email**: [api@royalti.io](mailto:api@royalti.io)