Tools - Royaltyport

The Royaltyport MCP server provides tools that let AI assistants browse projects, manage catalog data, upload files, and query financial analytics.

Project Tools

list_projects

List all projects for the authenticated organization. The organization is resolved automatically from your authentication token. Sample prompt: “Show me all my projects”

get_project

Get a project by ID.

Parameter	Type	Required	Default	Description
`projectId`	UUID	Yes	-	Project ID

Sample prompt: “Get details about project a1b2c3d4-…“

search_project

Search across all resources in a project — contracts, entities, artists, writers, recordings, and compositions.

Parameter	Type	Required	Default	Description
`projectId`	UUID	Yes	-	Project ID
`query`	string	Yes	-	Search query (1–500 characters)

Sample prompt: “Search for Sony in my project”

Contract Tools

list_contracts

List contracts for a project. Use includes to embed extracted sub-resource data inline.

Parameter	Type	Required	Default	Description
`projectId`	UUID	Yes	-	Project ID
`page`	integer	No	`1`	Page number
`perPage`	integer	No	`20`	Items per page (1–100)
`includes`	string[]	No	-	Sub-resources to include

Valid includes: entities, artists, writers, royalties, splits, costs, compensations, dates, accounting-periods, types, signatures, control-areas, creative-approvals, balances, recordings, compositions Sample prompt: “List all contracts with their royalty terms”

get_contract

Get a contract by ID with optional sub-resource includes.

Parameter	Type	Required	Default	Description
`contractId`	string	Yes	-	Contract ID
`projectId`	UUID	Yes	-	Project ID
`includes`	string[]	No	-	Sub-resources to include (same list as above)

Sample prompt: “Get contract abc-123 with entities and dates”

Entity Tools

list_entities

List root entities for a project — companies, labels, publishers, or other organizations.

Parameter	Type	Required	Default	Description
`projectId`	UUID	Yes	-	Project ID
`page`	integer	No	`1`	Page number
`perPage`	integer	No	`20`	Items per page (1–100)
`includeMerged`	boolean	No	`false`	Include merged (deduplicated) entities

Sample prompt: “List all entities in my project”

get_entity

Get an entity by ID with associated artists, writers, and relations.

Parameter	Type	Required	Default	Description
`entityId`	string	Yes	-	Entity ID
`projectId`	UUID	Yes	-	Project ID
`includeMerged`	boolean	No	`false`	Include merged entities

Sample prompt: “Get entity ent-456 with merged duplicates”

Artist Tools

list_artists

List root artists for a project — performers linked to recordings.

Parameter	Type	Required	Default	Description
`projectId`	UUID	Yes	-	Project ID
`page`	integer	No	`1`	Page number
`perPage`	integer	No	`20`	Items per page (1–100)
`includeMerged`	boolean	No	`false`	Include merged artists

Sample prompt: “Show me all artists in the project”

get_artist

Get an artist by ID.

Parameter	Type	Required	Default	Description
`artistId`	string	Yes	-	Artist ID
`projectId`	UUID	Yes	-	Project ID
`includeMerged`	boolean	No	`false`	Include merged artists

Sample prompt: “Get details for artist art-789”

Writer Tools

list_writers

List root writers for a project — songwriters and composers.

Parameter	Type	Required	Default	Description
`projectId`	UUID	Yes	-	Project ID
`page`	integer	No	`1`	Page number
`perPage`	integer	No	`20`	Items per page (1–100)
`includeMerged`	boolean	No	`false`	Include merged writers

Sample prompt: “List all writers in the project”

get_writer

Get a writer by ID.

Parameter	Type	Required	Default	Description
`writerId`	string	Yes	-	Writer ID
`projectId`	UUID	Yes	-	Project ID
`includeMerged`	boolean	No	`false`	Include merged writers

Sample prompt: “Get writer wrt-321”

Relation Tools

list_relations

List root relations for a project — contacts and people such as managers, A&R, and lawyers.

Parameter	Type	Required	Default	Description
`projectId`	UUID	Yes	-	Project ID
`page`	integer	No	`1`	Page number
`perPage`	integer	No	`20`	Items per page (1–100)
`includeMerged`	boolean	No	`false`	Include merged relations

Sample prompt: “Show all contacts in the project”

get_relation

Get a relation by ID.

Parameter	Type	Required	Default	Description
`relationId`	string	Yes	-	Relation ID
`projectId`	UUID	Yes	-	Project ID
`includeMerged`	boolean	No	`false`	Include merged relations

Sample prompt: “Get relation rel-654”

Recording Tools

list_recordings

List recordings for a project — audio tracks identified by ISRC codes.

Parameter	Type	Required	Default	Description
`projectId`	UUID	Yes	-	Project ID
`page`	integer	No	`1`	Page number
`perPage`	integer	No	`20`	Items per page (1–100)
`includeProducts`	boolean	No	`false`	Include associated products (albums, singles) with UPC codes

Sample prompt: “List recordings with their albums”

get_recording

Get a recording by ID with ISRC and artists.

Parameter	Type	Required	Default	Description
`recordingId`	string	Yes	-	Recording ID
`projectId`	UUID	Yes	-	Project ID
`includeProducts`	boolean	No	`false`	Include associated products

Sample prompt: “Get recording rec-111 with products”

Composition Tools

list_compositions

List compositions for a project — musical works identified by ISWC codes.

Parameter	Type	Required	Default	Description
`projectId`	UUID	Yes	-	Project ID
`page`	integer	No	`1`	Page number
`perPage`	integer	No	`20`	Items per page (1–100)
`includeProducts`	boolean	No	`false`	Include associated products

Sample prompt: “List all compositions in my project”

get_composition

Get a composition by ID with ISWC and linked writers.

Parameter	Type	Required	Default	Description
`compositionId`	string	Yes	-	Composition ID
`projectId`	UUID	Yes	-	Project ID
`includeProducts`	boolean	No	`false`	Include associated products

Sample prompt: “Get composition comp-222”

Statement Tools

list_statements

List statements for a project — royalty or revenue reports uploaded as files.

Parameter	Type	Required	Default	Description
`projectId`	UUID	Yes	-	Project ID
`page`	integer	No	`1`	Page number
`perPage`	integer	No	`20`	Items per page (1–100)

Sample prompt: “Show all statements in the project”

For querying the actual revenue data within statements, use the query tool with BigQuery SQL instead.

get_statement

Get a statement by ID with processing status and currency.

Parameter	Type	Required	Default	Description
`statementId`	string	Yes	-	Statement ID
`projectId`	UUID	Yes	-	Project ID

Sample prompt: “Get statement 1234”

Upload Tools

upload_file

Create a staging record and return a signed upload URL. Upload the file via HTTP PUT to the returned uploadUrl. After the upload completes, you must call upload_completed to trigger processing.

Parameter	Type	Required	Default	Description
`projectId`	UUID	Yes	-	Project ID
`resourceType`	string	Yes	-	`contract` or `statement`
`fileName`	string	Yes	-	Original file name (e.g. `contract.pdf`)
`fileType`	string	No	`application/pdf`	MIME type of the file
`fileSize`	integer	Yes	-	File size in bytes
`extractions`	string[]	No	-	Extractions to run after upload (contract only)

Valid extractions: entities, artists, writers, royalties, splits, costs, compensations, dates, accounting-periods, types, signatures, control-areas, creative-approvals, balances, recordings, compositions Sample prompt: “Upload contract.pdf and extract royalties and dates”

upload_completed

Signal that a file upload is complete. Call this after successfully uploading the file via HTTP PUT to the uploadUrl returned by upload_file. This triggers processing.

Parameter	Type	Required	Default	Description
`stagingId`	string	Yes	-	Staging ID returned from `upload_file`
`projectId`	UUID	Yes	-	Project ID
`resourceType`	string	Yes	-	`contract` or `statement`

Sample prompt: “Signal that upload stg-456 is complete”

upload_status

Check the processing status of an uploaded contract or statement.

Parameter	Type	Required	Default	Description
`stagingId`	string	Yes	-	Staging ID returned from `upload_file`
`projectId`	UUID	Yes	-	Project ID
`resourceType`	string	Yes	-	`contract` or `statement`

Sample prompt: “Check the status of upload stg-456”

Download Tools

download_file

Get a signed download URL for a contract or statement file. The URL expires in 1 hour.

Parameter	Type	Required	Default	Description
`resourceId`	string	Yes	-	Contract ID or Statement ID
`projectId`	UUID	Yes	-	Project ID
`resourceType`	string	Yes	-	`contract` or `statement`

Sample prompt: “Download contract abc-123”

BigQuery Tools

list_tables

Lists available BigQuery tables and their schemas. Returns a compact summary by default. Set verbose to true to include full column details (name, data type, description).

Parameter	Type	Required	Default	Description
`datasets`	string[]	No	`["rp_data_external", "rp_data_intermediate"]`	Filter by dataset name
`verbose`	boolean	No	`false`	When `true`, includes column details (name, data type)

Available datasets: rp_data_external, rp_data_intermediate Sample prompt: “What tables are available for querying?“

query

Execute a read-only SQL query against BigQuery. Use this for financial analytics — revenue breakdowns, cost reports, statement-level data, and period comparisons. Every referenced table must be filtered by project_id = @project_id (use table aliases in JOINs, e.g., a.project_id = @project_id AND b.project_id = @project_id). The @project_id parameter is automatically bound to the current project ID. Use standard SQL syntax (not PostgreSQL). Always use fully qualified table names (e.g., rp_data_external.recording_revenues_ext).

Parameter	Type	Required	Default	Description
`sql`	string	Yes	-	SQL query with `@project_id` named parameter
`projectId`	UUID	External auth only	Auto-injected	Project ID (required for external auth, auto-injected for internal)
`offset`	integer	No	`0`	Number of rows to skip. Use with truncated results to paginate (e.g., `offset=1000` for the next page)

Example query:

SELECT
  recording_name,
  SUM(net_receipts_eur) AS total_revenue
FROM rp_data_external.recording_revenues_ext
WHERE project_id = @project_id
GROUP BY recording_name
ORDER BY total_revenue DESC
LIMIT 10

Results are capped at 1,000 rows. If the query returns more, truncated will be true in the response. Use offset to paginate through large result sets. Sample prompt: “What are the top 10 recordings by revenue?”

Getting Started

MCP

​Project Tools

​list_projects

​get_project

​search_project

​Contract Tools

​list_contracts

​get_contract

​Entity Tools

​list_entities

​get_entity

​Artist Tools

​list_artists

​get_artist

​Writer Tools

​list_writers

​get_writer

​Relation Tools

​list_relations

​get_relation

​Recording Tools

​list_recordings

​get_recording

​Composition Tools

​list_compositions

​get_composition

​Statement Tools

​list_statements

​get_statement

​Upload Tools

​upload_file

​upload_completed

​upload_status

​Download Tools

​download_file

​BigQuery Tools

​list_tables

​query

Project Tools

list_projects

get_project

search_project

Contract Tools

list_contracts

get_contract

Entity Tools

list_entities

get_entity

Artist Tools

list_artists

get_artist

Writer Tools

list_writers

get_writer

Relation Tools

list_relations

get_relation

Recording Tools

list_recordings

get_recording

Composition Tools

list_compositions

get_composition

Statement Tools

list_statements

get_statement

Upload Tools

upload_file

upload_completed

upload_status

Download Tools

download_file

BigQuery Tools

list_tables

query