Skip to content

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_workspace and select_workspace;
  • link_to_app;
  • the society reads list_societies, get_society and list_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.

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.

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.

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.

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

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.

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.

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

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

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.

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.

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

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 id keeps that row; omit id to 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, ipn and a name’s ipiCae, but the API never returns them.
  • Per field the absence rule applies: an omitted field is untouched, null clears where allowed, [] clears a list.

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.

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)

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

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

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

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 same rule applies to every write:

  • An omitted section is left unchanged.
  • An explicit empty array [] clears that section.
  • active: false deactivates the society.
  • Nothing is ever hard-deleted.