sync_group_members
Replace a group's membership wholesale. A sync, not an add.
Replaces a group's membership with exactly the supplied user ids.
This is a sync, not an add
Anyone absent from user_ids is removed, and an empty array empties the
group. Read the current membership with
list_groups and send the full intended list — not
just the people you want to add.
Every id must already belong to the group's team. A group grants permissions inside one tenant, so an outsider is refused rather than silently skipped — and the whole call fails rather than partly applying, so you never end up with a membership you did not ask for.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same action as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Fires one event
Delivered to every endpoint subscribed to it once the change is made.
Annotations
A client that honours annotations asks a person before running it. It reaches beyond Subscriby: a connector, a provider or a member.
Arguments
group_id*stringUUID of the group whose membership is being replaced.
user_ids*arrayComplete list of user UUIDs the group should contain. An empty array clears it.
What it returns
{ "data": { "id": "1f68d92a-04c5-4e83-97b1-3d6a05e2f847", "team_id": "a83f0d51-4c92-4b7e-8615-2fd9e70a3c86", "member_ids": [ "2a91c4e7-6f38-4b52-8e0d-9c1a7b3f5d80", "6f9b2e37-c184-4a05-8d72-30e16bc9f458" ] }}Emits group.members_synced, carrying added_ids and removed_ids as well as the final list — an access-control mirror should not have to diff two snapshots to work out what moved.
A sync that changes nothing emits nothing.
How it fails
AUTHENTICATION_REQUIREDno authenticated user on the request.
TOKEN_MISSING_ABILITYtoken lacks group:update.
TEAM_TIER_REQUIREDthe sync adds somebody and the caller's tier does not include Teams. Nothing changes.
RESOURCE_NOT_FOUNDno such group in any team the caller belongs to.
VALIDATION_FAILEDone or more ids are not in the group's team. The offending ids are named, and nothing is applied.
Tier
Gated on Growth only when the sync adds somebody. A sync that only removes people succeeds on any tier.
This is the one write in the identity surface whose gate depends on its argument. Deciding from the tool alone would leave a lapsed creator unable to take one person out of a group without deleting the whole group — and deleting is not gated, so the gate would only be pushing them toward the more destructive option. See what the tier gates.
How is this guide?
Last updated on