Roles, members & seats

systemHUB controls who can see and do what through roles and member assignments. This page explains the model an agent needs to reason about access — and where the current MCP boundary sits.

The access model

A document’s access is the union of two mechanisms:

• Role-based access — a document is assigned to one or more roles (e.g. a department or job function). Every member holding that role gets access.
• Direct assignment — an individual member is assigned to the document specifically, regardless of role.

A member can therefore have access that is direct, role-based, or both. The get_document_members_and_roles tool returns exactly this: the roles on a document, plus each member’s name, email, role title(s), and access type.

Present an access picture as an audit: roles first, then members grouped by how they got in (direct vs role-based vs both).

Document owners

Separate from access, every document carries a primary owner (mandatory — the person accountable for it) and an optional secondary owner (a backup). Owners are about accountability, not permission: owning a document is not what grants access to it.

Three behaviours to know before changing owners programmatically:

Changing the primary owner moves the outgoing owner into an empty secondary slot. If the secondary slot is empty, the person you just replaced is automatically recorded as secondary owner — the intent being that a handover keeps the previous owner attached as backup. If a distinct secondary owner already occupies the slot, it is left untouched and the outgoing owner simply drops off. This fires on every owner change and is not reported in the response, so re-read the document after reassigning rather than assuming the secondary slot is unchanged.

• A secondary owner equal to the primary owner is treated as no secondary owner. It is returned as null and displayed as empty. This is why list_documents_by_owner describes matching a distinct secondary owner, and why a document can appear to gain a secondary owner the moment its primary changes.
• To clear a secondary owner, pass secondaryOwner: null on edit_system / edit_policy / edit_training. Omitting the field leaves it unchanged.

Reassigning in bulk (e.g. someone leaving): deleting a user in the app UI is the intended path — it asks for a replacement primary and secondary owner and swaps the departing person out of both slots across every document in one action, without triggering the auto-fill above. Reassigning documents one at a time instead means the auto-fill applies to each, so plan on a second pass to tidy the secondary slots.

Seats

A seat is a licensed member of the workspace. Seat/member management — inviting people, allocating seats, changing who holds which role — is done in the systemHUB app UI.

MCP boundary (important for connecting agents): the MCP can read the full access picture (members, roles, assignment type, agreement status, training progress) and can write document-level access — manage_document_members assigns or removes members and roles on a document, with list_company_members / list_roles to resolve names to UUIDs. What it can not do is seat provisioning: inviting new people to the workspace, allocating licences, or changing who holds which company role. That stays in the app UI — direct the user there.

What agents can audit today

• get_document_members_and_roles — who can access a document, and how.
• get_document_agreement_status — who has agreed/signed off on a document (e.g. a policy acknowledgement).
• get_document_training_progress — for trainings, each assigned user’s completion percentage and status.
• get_document_activity_log — who created and last modified a document, plus the event feed (includeViews: true to include views).
• list_documents_by_owner — everything a given person owns across systems, policies, and trainings, in one call.

⚠️ manage_document_members with action: "update" REPLACES the document’s assigned roles — it does not merge. Passing a partial list silently removes every role you left out. To add or remove without collateral damage, use action: "add" / "remove". Always confirm the result with get_document_members_and_roles.

Paginate deliberately. The audit tools page their results. Pass fetchAll: true (the default on most) when you need a complete roster — a partial page will otherwise be reported as the whole answer, which is how an agent confidently states the wrong list of who has signed off.

Together these cover “who owns / can see / has completed what” — the read side of governance. The write side (provisioning) stays in the app for now.

Next: Authoring content →