MCP tools

Published verbatim from Gungner’s Brayns partner interface pack, version 1.6.0 (mcp-tools.md). This page is not edited here.

Every MCP tool — one per row, mapping 1:1 onto the REST route(s) in reference.md. Same tokens, same scopes, same audit trail: nothing reachable here that is not reachable over REST with the same token. The machine-readable form of this file is mcp-tools.json.

Connecting

• Transport: MCP Streamable HTTP at /mcp on the API’s own origin — the same host and port as /v1/*. Stateless: no session id is issued and no SSE stream is opened; every response is JSON. GET and DELETE on /mcp are 405.
• Authentication: Authorization: Bearer <token>, the same credential as REST. A missing, invalid, expired or revoked one is 401 before any MCP message is read — there is no anonymous initialize or tools/list.
• Discovery: tools/list shows the tools your scopes open (each tool below names the scopes that list it). It grants nothing: calling a tool you were not shown is answered by the API as over REST — typically 403 forbidden, relayed as an isError result carrying the API’s own error code.
• Results: content[0] is a one-line summary; content[1] is the REST response body, byte for byte (for the two lookup_* tools, the serialised composition); structuredContent is that body plus summary, and validates against the tool’s outputSchema where it has one. Errors: content[0] is <error code>: <message>, content[1] the API’s error body.
• Audit: every tool call is one mcp.tool_call row in your tenant’s audit log, whatever its outcome, beside exactly the rows the same REST calls would write.

end_subscription — End a subscription

Stops monitoring a subject. One-way: scheduled work is cancelled immediately and no upstream call is made for that subject on this tenant’s behalf afterwards; tenant-private derived data is purged after the tenant’s retention period. Requires monitoring:subscribe.

• Scope: monitoring:subscribe

• Maps to: POST /v1/subscriptions/{id}/end

• Annotations: readOnlyHint false, destructiveHint false, idempotentHint false

• Output schema: the 200 response of POST /v1/subscriptions/{id}/end, plus summary

• Input schema:

  • subscription_id: string

get_beneficial_owners — Get beneficial owners

Beneficial owners (verkliga huvudmän) for a Swedish organisationsnummer. Paid source (Bolagsverket företagsinformation) — metered per tenant. Requires kyb:read.

• Scope: kyb:read

• Maps to: GET /v1/companies/{orgnr}/beneficial-owners

• Annotations: readOnlyHint true, destructiveHint false, idempotentHint true

• Output schema: the 200 response of GET /v1/companies/{orgnr}/beneficial-owners, plus summary

• Input schema:

  • orgnr: string

get_company_profile — Get company profile

Company profile, status and tax placeholder for a Swedish organisationsnummer. Free source (Bolagsverket värdefulla datamängder). Requires kyb:read.

• Scope: kyb:read

• Maps to: GET /v1/companies/{orgnr}

• Annotations: readOnlyHint true, destructiveHint false, idempotentHint true

• Output schema: the 200 response of GET /v1/companies/{orgnr}, plus summary

• Input schema:

  • orgnr: string

get_officers — Get officers

Officers and the signatory rule (funktionärer + firmateckning) for a Swedish organisationsnummer. Paid source (Bolagsverket företagsinformation) — metered per tenant. Requires kyb:read.

• Scope: kyb:read

• Maps to: GET /v1/companies/{orgnr}/officers

• Annotations: readOnlyHint true, destructiveHint false, idempotentHint true

• Output schema: the 200 response of GET /v1/companies/{orgnr}/officers, plus summary

• Input schema:

  • orgnr: string

get_person_engagements — Get person engagements

A person’s beneficial-owner and officer engagements across companies, addressed by identifier_ref (never a personnummer). Paid source (Bolagsverket företagsinformation) — metered per tenant. Requires kyb:read.

• Scope: kyb:read

• Maps to: GET /v1/persons/{ref}/engagements

• Annotations: readOnlyHint true, destructiveHint false, idempotentHint true

• Output schema: the 200 response of GET /v1/persons/{ref}/engagements, plus summary

• Input schema:

  • ref: string

get_person_profile — Get person profile

The SPAR person profile — names, birth date, folkbokföring and protection markers — addressed by identifier_ref (never a personnummer). Read from Swedish population register data under the tenant’s own SPAR permit: a tenant without an active permit gets 403 spar_permit_required and no upstream call is made. Under a protection marker (sekretessmarkering or skyddad folkbokföring) no address is returned — the marker is the data. Never served stale. Metered per tenant. Requires kyc:read.

• Scope: kyc:read

• Maps to: GET /v1/persons/{ref}

• Annotations: readOnlyHint true, destructiveHint false, idempotentHint true

• Output schema: the 200 response of GET /v1/persons/{ref}, plus summary

• Input schema:

  • ref: string

get_screening_check — Get a screening check

One screening check and its candidates, with the policy, override, source and matcher versions it was produced under — enough to re-run it and get the same result. Identifiers in the input snapshot are masked unless the caller also holds kyc:read, and on a check of a person the name and birth date are masked too — input_snapshot.person_fields_masked says when that happened, so a blank name is never mistaken for an absent one. Requires screening:read.

• Scope: screening:read (also listed for screening:run)

• Maps to: GET /v1/screening/checks/{id}

• Annotations: readOnlyHint true, destructiveHint false, idempotentHint true

• Output schema: the 200 response of GET /v1/screening/checks/{id}, plus summary

• Input schema:

  • id: string

get_signatories — Get signatories

Signatory rule (firmateckning) for a Swedish organisationsnummer — same underlying object as get_officers. Paid source (Bolagsverket företagsinformation) — metered per tenant. Requires kyb:read.

• Scope: kyb:read

• Maps to: GET /v1/companies/{orgnr}/signatories

• Annotations: readOnlyHint true, destructiveHint false, idempotentHint true

• Output schema: the 200 response of GET /v1/companies/{orgnr}/signatories, plus summary

• Input schema:

  • orgnr: string

get_subject — Get subject

The canonical subject object — aliases, identifiers and customer references — for a Gungner subject id. No upstream cost. Requires kyb:read.

• Scope: kyb:read

• Maps to: GET /v1/subjects/{id}

• Annotations: readOnlyHint true, destructiveHint false, idempotentHint true

• Output schema: the 200 response of GET /v1/subjects/{id}, plus summary

• Input schema:

  • id: string

get_subscription — Get a subscription

One monitoring subscription by id — subject, kind, legal basis, status and next run. Read-only: it starts and stops nothing. A subscription of a kind this token may not read answers exactly like one that does not exist. No upstream cost. Requires monitoring:read (monitoring:subscribe, kyb:read or kyc:read also open it, the last two for the matching kind only).

• Scope: monitoring:read (also listed for monitoring:subscribe)

• Maps to: GET /v1/subscriptions/{id}

• Annotations: readOnlyHint true, destructiveHint false, idempotentHint true

• Output schema: the 200 response of GET /v1/subscriptions/{id}, plus summary

• Input schema:

  • id: string

list_changes — List changes

Replays this tenant’s monitoring change events from a cursor — company, status, signatory, UBO and person changes only, the same log as list_events with the change types preselected. No upstream cost. Requires events:read.

• Scope: events:read

• Maps to: GET /v1/events

• Annotations: readOnlyHint true, destructiveHint false, idempotentHint true

• Output schema: the 200 response of GET /v1/events, plus summary

• Input schema:

  • cursor (optional): string
  • limit (optional): number

list_events — List events

Replays this tenant’s event log from a cursor — gap-free, replayable, at-least-once. No upstream cost. Requires events:read.

• Scope: events:read

• Maps to: GET /v1/events

• Annotations: readOnlyHint true, destructiveHint false, idempotentHint true

• Output schema: the 200 response of GET /v1/events, plus summary

• Input schema:

  • cursor (optional): string
  • limit (optional): number

list_screening_checks — List screening checks

This tenant’s screening checks, newest first, optionally for one subject. Requires screening:read.

• Scope: screening:read (also listed for screening:run)

• Maps to: GET /v1/screening/checks

• Annotations: readOnlyHint true, destructiveHint false, idempotentHint true

• Output schema: the 200 response of GET /v1/screening/checks, plus summary

• Input schema:

  • limit (optional): number
  • subject_id (optional): string

list_screening_overrides — List screening overrides

This tenant’s screening policy override versions, newest first — each version’s configuration, status (draft, approved, active or retired), proposer, approver and effective date. Read-only. Requires screening:read.

• Scope: screening:read

• Maps to: GET /v1/screening/overrides

• Annotations: readOnlyHint true, destructiveHint false, idempotentHint true

• Output schema: the 200 response of GET /v1/screening/overrides, plus summary

• Input schema:

  • none

list_screening_whitelist — List screening whitelist

This tenant’s screening whitelist entries, newest first — which list entry is suppressed for which subject, the stated reason, who created and who approved it, when it expires, and whether it is in effect now. Read-only: entries are created and approved through the tenant’s own four-eyes process, not here. Requires screening:read.

• Scope: screening:read

• Maps to: GET /v1/screening/whitelist

• Annotations: readOnlyHint true, destructiveHint false, idempotentHint true

• Output schema: the 200 response of GET /v1/screening/whitelist, plus summary

• Input schema:

  • none

list_subscriptions — List subscriptions

This tenant’s monitoring subscriptions — which subjects are watched, under which legal basis, at what cadence, and when each next runs. Read-only: it starts and stops nothing. No upstream cost. Requires monitoring:read (monitoring:subscribe, kyb:read or kyc:read also open it, the last two filtered to the matching kind).

• Scope: monitoring:read (also listed for monitoring:subscribe)

• Maps to: GET /v1/subscriptions

• Annotations: readOnlyHint true, destructiveHint false, idempotentHint true

• Output schema: the 200 response of GET /v1/subscriptions, plus summary

• Input schema:

  • limit (optional): number
  • status (optional): string

lookup_company — Lookup company

Resolves a Swedish organisationsnummer to its canonical Gungner subject id (creating one on first sight) and returns the company profile in one call. Free source (Bolagsverket värdefulla datamängder). Requires kyb:read.

• Scope: kyb:read

• Maps to: POST /v1/subjects/resolve + GET /v1/companies/{orgnr}

• Annotations: readOnlyHint true, destructiveHint false, idempotentHint true

• Output schema: none — the result composes more than one route

• Input schema:

  • orgnr: string

lookup_person — Lookup person

Resolves a Swedish personnummer or samordningsnummer to its canonical Gungner subject id (creating one on first sight) and returns the SPAR person profile in one call — the identifier goes in, an identifier_ref is what Gungner stores and echoes, and the raw identifier is never returned. Read under the tenant’s own SPAR permit: a tenant without an active permit gets 403 spar_permit_required (or 403 spar_permit_suspended) and no upstream call is made, before any cache is read. Under a protection marker (sekretessmarkering or skyddad folkbokföring) nothing that locates the person is returned — the marker is the data. Never served stale: SPAR unavailable is 503, not an out-of-date profile. Metered per tenant against the kyc budget. Requires kyc:read.

• Scope: kyc:read

• Maps to: POST /v1/subjects/resolve + GET /v1/persons/{ref}

• Annotations: readOnlyHint true, destructiveHint false, idempotentHint true

• Output schema: none — the result composes more than one route

• Input schema:

  • identifier: string
  • type: unknown

refresh_company — Refresh company

Forces a paid upstream re-fetch of the company profile and returns it; while an active monitoring subscription covers the company, change events are emitted for what moved. Triggers a paid upstream refresh every time it is called — it never answers from cache — metered per tenant. Requires kyb:refresh.

• Scope: kyb:refresh

• Maps to: POST /v1/companies/{orgnr}/refresh

• Annotations: readOnlyHint false, destructiveHint false, idempotentHint false

• Output schema: the 200 response of POST /v1/companies/{orgnr}/refresh, plus summary

• Input schema:

  • orgnr: string

screen_subject — Screen a subject

Runs a sanctions screening check against the lists this tenant is licensed for, and returns scored candidates with structured reasons and evidence. Takes either a Gungner subject id or an ad-hoc identity (name, birth date, nationalities, orgnr, country). Bands are clear, review or hit; the reasons say what agreed and what did not. Gungner reports what the lists say and never what to do about it. Requires screening:run, which also opens the screening reads — and kyc:read as well when the subject is a person, because screening one reads its name and birth date from SPAR.

• Scope: screening:run

• Maps to: POST /v1/screening/checks

• Annotations: readOnlyHint false, destructiveHint false, idempotentHint false

• Output schema: the 201 response of POST /v1/screening/checks, plus summary

• Input schema:

  • birth_date (optional): string
  • country (optional): string
  • name (optional): string
  • nationalities (optional): unknown
  • orgnr (optional): string
  • subject_id (optional): string

subscribe_monitoring — Subscribe to monitoring

Starts monitoring a subject under a stated legal basis (aml_cdd, contract, legal_obligation, consent, legitimate_interest). Person subjects additionally require the tenant’s active SPAR permit. Changes arrive as events; read them with list_changes. Requires monitoring:subscribe.

• Scope: monitoring:subscribe

• Maps to: POST /v1/subscriptions

• Annotations: readOnlyHint false, destructiveHint false, idempotentHint false

• Output schema: the 201 response of POST /v1/subscriptions, plus summary

• Input schema:

  • kind: string
  • legal_basis: string
  • legal_basis_ref (optional): string
  • subject_id: string

Operations with no tool

Every other operation the API serves, and why it has no MCP tool:

• GET /v1/documents/{id} — binary: the body is a zip archive (the annual-report filing) carried base64-encoded in JSON — nothing an agent can read, and costly to put in its context. The document metadata agents need is latest_annual_report {year, ref} on the company profile (get_company_profile, lookup_company).
• /oauth/token* — credential exchange: how a consumer obtains the bearer an MCP client presents, not an operation on data.
• /v1/portal/* — human-session surface (SPEC-006a): authenticated by a portal session, never by a consumer credential.
• /v1/assistant/* — human-session surface (SPEC-006b): the portal assistant, authenticated by a portal session; its message endpoint is a server-sent-event stream. The assistant drives the same tools from the other side.