MCP tools
The MCP server has two kinds of tools.
User tools run as you, with your own emely sign-in (scope openid graphql:role:user). They see and do exactly what you see and do in the emely app, never more. An answer carries only the fields named for each tool. With your own sign-in you have eight tools:
- the workspace tools
list_my_workspaces,current_workspaceandselect_workspace; link_to_app;- the society reads
list_societies,get_societyandlist_reference_values; list_my_society_memberships.
The assistant reads your memberships; it does not change them yet, so use the emely app for that. Your connection lists only these eight tools.
One workspace at a time. The assistant works in one workspace you chose. See The workspace switch. Every answer is JSON with a workspace field {id, name} that says which workspace it is about. It is null for the society catalogue and its lists, which belong to no workspace, and while no workspace is chosen. A refusal is {error, workspace}. If you were removed from the workspace you chose, workspace is {id, name: null} and the answer asks you to choose again.
Api tools serve scripts and staff on the api roles. Their arguments mirror the REST API, which is documented in the API reference. A user token runs the eight tools above and nothing else; it cannot call the staff tools (create_or_update_society, the import and identity tools). An api token cannot call list_my_workspaces. Your connection lists only the tools your token can run.
list_my_workspaces
Section titled “list_my_workspaces”Lists the workspaces you belong to, as the app’s workspace switcher shows them. Scope: user. Read-only, no arguments.
The answer is {workspaces: [{id, name, kind, myRole, plan, chosen}], workspace}:
| Field | Description |
|---|---|
id |
The workspace id |
name |
The workspace name |
kind |
individual or organisation |
myRole |
Your role in the workspace: owner, admin, manager or member |
plan |
The workspace’s plan |
chosen |
true for the workspace this assistant works in |
A person with no workspace yet gets an empty list; create one in the emely app.
current_workspace
Section titled “current_workspace”Says which workspace this assistant works in. Scope: user. Read-only, no arguments.
The answer is {message, workspace}. workspace is the chosen workspace {id, name}, or null when none is chosen yet. In that case message says how to choose one: if you have only one workspace it names it, and if you have none it links to the app to create one. If you are no longer a member of the chosen workspace, the call is refused and asks you to choose again.
select_workspace
Section titled “select_workspace”Chooses the workspace this assistant works in. Scope: user. This is the only way to switch.
| Argument | Type | Required | Description |
|---|---|---|---|
workspaceId |
string | yes | A workspace id from list_my_workspaces |
The answer is {left, chosen, message, workspace}. left is the workspace you left, {id, name}, or null on the first choice. chosen and workspace are the workspace now chosen. message names both in a sentence. A workspace you are not a member of is refused, and the choice stays as it was.
link_to_app
Section titled “link_to_app”Some things are done in the emely app, not through the assistant. This tool answers the link to the right screen. Scope: user. Read-only.
| Argument | Type | Required | Description |
|---|---|---|---|
topic |
string | yes | One of the topics below |
artistId |
string | no | For pictures and artist_persons: the artist, to link straight to its page |
| Topic | What it is for |
|---|---|
billing |
Payments, invoices and plan changes |
sign_in |
Password and sign-in |
connected_apps |
Connected assistants and apps, and disconnecting one |
api_tokens |
Personal access tokens for the API |
audio_masters |
Uploading and replacing audio masters |
pictures |
Uploading and cropping artist pictures and covers |
artist_persons |
The private person records behind artists: name, contact, address, date of birth |
label_contacts |
The contacts of your labels and your company |
create_workspace |
Creating your first workspace |
The answer is {topic, url, what, message, workspace}.
Rate limit
Section titled “Rate limit”Each person can make at most 60 changes and 300 reads a minute on each server instance (the limit is per person on each server instance, so it is not shared across instances). A call over the limit is refused with “Slow down” and the number of seconds to wait. Nothing is sent.
Api tools
Section titled “Api tools”Which api tools you can call depends on your token’s scope. The society reads and list_my_society_memberships also work with your own sign-in (scope user), as you, with your app rights; set_my_society_memberships does not; the rest of this section describes them on the api roles. Catalogue tools serve both api_operator and api_user; create_or_update_society and the six import tools require api_operator; the membership tools require api_user. See Get a token. A personal access token is always api_user, so it can never call the import tools - sign in through OAuth as an operator.
list_societies
Section titled “list_societies”Lists societies in the catalogue. The list is paginated. Scope: user, api_operator or api_user.
| Argument | Type | Required | Description |
|---|---|---|---|
active |
string | no | 'true' or 'false', filters by active status |
country |
string | no | Filter by home country code |
q |
string | no | Search by name or code |
limit |
integer | no | Page size, 1 to 200, default 50 |
offset |
integer | no | Page offset, default 0 |
get_society
Section titled “get_society”Returns one society with its roles, sourced rights, detail rights and links. Scope: user, api_operator or api_user.
| Argument | Type | Required | Description |
|---|---|---|---|
code |
string | yes | The society’s code |
list_reference_values
Section titled “list_reference_values”Returns one reference vocabulary. Scope: user, api_operator or api_user. The agency-kinds vocabulary and the 23 catalog-import vocabularies are not available to api_user or user tokens; with your own sign-in you read right-types, right-subtypes, society-types, society-roles and countries.
| Argument | Type | Required | Description |
|---|---|---|---|
vocabulary |
string | yes | One of right-types, right-subtypes, society-types, society-roles, agency-kinds, countries, or an import vocabulary: artist-kinds, artist-credit-roles, performer-roles, studio-roles, work-writer-roles, title-kinds, languages, genres, music-types, product-kinds, configuration-kinds, vinyl-sizes, vinyl-speeds, surround-formats, recording-types, recording-track-kinds, audio-presentations, audio-bit-depths, audio-sample-rates, audio-channel-configurations, immersive-audio-formats, language-content-kinds, external-systems |
Item shape differs per vocabulary. genres returns {code, name, groupCode, sortOrder} and performer-roles, studio-roles and work-writer-roles return {value, name, sortOrder} - the active vocabulary only, in sortOrder, name being the English display name a mapper matches a sheet’s text against. The other vocabularies return {value, comment}, {code} or {code, name} items as before, in alphabetical order.
create_or_update_society
Section titled “create_or_update_society”Creates or updates one society. code is the natural key: an unknown code creates, a known code updates. Scope: api_operator.
| Argument | Type | Required | Description |
|---|---|---|---|
code |
string | yes | The society’s code |
name |
string | on create | Display name |
kind |
string | on create | An agency-kinds value |
homeCountryCode |
string | no | Home country code; null clears |
cisacCode |
string | no | CISAC society code; null clears |
comment |
string | no | Free-text comment; null clears |
active |
boolean | no | false deactivates the society |
roles |
array | no | { role, societyType } entries |
rights |
array of strings | no | Right types the society collects: pr, mr, nr, sr |
detailRights |
array | no | { role, rightType, countryCode, subRights } entries |
links |
array | no | { linkedAgencyCode, rightType } entries |
Valid values for role, societyType and the detail-right subRights come from list_reference_values.
list_my_society_memberships
Section titled “list_my_society_memberships”Lists your own society memberships: your person’s songwriter and performer rows and the publisher and label rows of the workspace you chose. With your own sign-in (scope user) it follows the chosen workspace like every other tool: with none chosen it lists only your own songwriter and performer rows and adds a hint to choose a workspace for publisher and label memberships. With an api token (scope api_user) it lists the rows of all your workspaces. Scope: user or api_user.
| Argument | Type | Required | Description |
|---|---|---|---|
role |
string | no | Limit to one of songwriter, performer, publisher, label; omitted returns all |
Identifiers are never shown. The hasMemberNumber, hasIpiBaseNumber and hasIpn flags say whether one is on file. Each row’s owner is {type: "person"} for your songwriter and performer memberships, or {type: "workspace", workspace} for publisher and label ones; the workspace object carries id, name, kind and organisationKind (the organisation subtype: label, publisher or manager, null on an individual workspace).
set_my_society_memberships
Section titled “set_my_society_memberships”Replaces your membership list for one role. Scope: api_user only. It is not available with your own sign-in (scope user) yet; change memberships in the emely app.
| Argument | Type | Required | Description |
|---|---|---|---|
role |
string | yes | The role whose list this call replaces |
workspaceId |
string | see note | For publisher and label: which of your workspaces owns the memberships; required when you belong to several |
memberships |
array | yes | The full new list for the role; [] removes all |
- The call replaces the whole list for that role. An entry with an existing
idkeeps that row; omitidto insert a new one. An id that is not one of your current rows is refused. - Identifiers are write-only. You can send
memberNumber,ipiBaseNumber,ipnand a name’sipiCae, but the API never returns them. - Per field the absence rule applies: an omitted field is untouched,
nullclears where allowed,[]clears a list.
describe_import_format
Section titled “describe_import_format”Returns the emely-catalog-import v1 contract: the JSON Schema every import document is validated against, its schemaSha256, the limits (part ≤ 64 KB, document ≤ 2 MB, ≤ 5000 items), the mapper guidance, and the 23 vocabularies the document draws its enumerations from. Scope: api_operator. Takes no arguments. See Catalog import.
start_import_draft
Section titled “start_import_draft”Opens an import draft in a workspace. Returns draftId and the limits. Scope: api_operator.
| Argument | Type | Required | Description |
|---|---|---|---|
workspaceId |
string | yes | The workspace UUID the import applies to |
source |
object | yes | Names the import; every row it writes carries it. Pass fileName or description (mappedBy optional) |
add_import_draft_part
Section titled “add_import_draft_part”Sends one part of one section of the document. Each items array is at most 64 KB. Resending the same {section, part} replaces it. A refused part comes back as a tool error listing the part errors. Scope: api_operator.
| Argument | Type | Required | Description |
|---|---|---|---|
draftId |
string | yes | The draft id from start_import_draft |
section |
string | yes | parties, works, recordings, products or unmapped |
part |
integer | yes | 1-based part index within the section |
items |
array | yes | The section slice; JSON ≤ 64 KB |
dry_run_import
Section titled “dry_run_import”Assembles the draft parts, validates the document against the schema, matches every referenced entity against the catalog, and stores a plan with a paged report. Writes nothing to the catalog. Scope: api_operator.
| Argument | Type | Required | Description |
|---|---|---|---|
draftId |
string | yes | The draft id |
matches |
object | no | Resolutions for ambiguous matches from an earlier dry run: "section:ref" to an existing row id, or "new" to create |
Ambiguous items come back in ambiguous with their candidates; resolve them and dry-run again. The response carries planId, schemaSha256, totals, bound, unmappedCount, warnings, skipped and reportPages. bound is the count of refs bound to an earlier applied plan of the same draft, not the count of matched items.
Status is reported in-band on a 200: planned means a plan was stored; busy means another call holds the draft’s lease, so wait and retry; invalid means the document failed validation, so read errors and resend the parts. get_import_plan can answer stale when the draft changed after the plan was stored, so dry-run again. apply_import_plan answers applied (every unit committed), partial (the call’s time box ran out with remainingUnits left; call apply again to resume), applied_with_failures (finished, but some units failed or were blocked; read failedUnits, blockedUnits and droppedOps, and a repeat call reports the same verdict), busy (the draft lease is held by another call or was lost mid-run; wait and retry), stale (the draft’s parts changed since the dry run; dry-run again) or already_applied (a repeat call that wrote nothing).
get_import_plan
Section titled “get_import_plan”Reads one page of a stored plan’s report: status, schemaSha256, the ledger of planned writes, and the report text for that page. Scope: api_operator.
| Argument | Type | Required | Description |
|---|---|---|---|
planId |
string | yes | The plan id from dry_run_import |
page |
integer | no | Report page, default 1; the response carries pages |
apply_import_plan
Section titled “apply_import_plan”Executes a stored, reviewed plan: writes the planned catalog rows and their provenance claims. Read every report page first. Applying the same plan again creates no new claims. Scope: api_operator.
| Argument | Type | Required | Description |
|---|---|---|---|
planId |
string | yes | The plan id from dry_run_import |
The response lists applied, remainingUnits, failedUnits, blockedUnits, staleUnits and droppedOps so a partial run can be read and retried.
The absence rule
Section titled “The absence rule”The same rule applies to every write:
- An omitted section is left unchanged.
- An explicit empty array
[]clears that section. active: falsedeactivates the society.- Nothing is ever hard-deleted.