MCP tools: remote-user-tokens

All tool groups

remote-user-tokens

Registered when: a USER-TOKEN (gqut_) MCP session only, while the platform setting userTokens.enabled holds (default off since review round 2); never an org API key, so no key's list changes. create_org is listed only for the bootstrap-email rollout while userTokens.orgAdmin is on; add_org_member, set_org_member_role and remove_org_member use live org authority, with a reasoned platform-admin ownership override supported by set_org_member_role; user_tokens_create is omitted while human-only minting is on. Each tool calls the same REST route with the token, so its abilities, mint-chain rules and approval switch apply (docs/design/USER-TOKENS.md).

add_org_member

Add an existing user to an org as an org admin/owner. User tokens need members.manage; only owners can grant owner. Use invite_to_org for a new account.

Parameter	Type	Required	Description
orgId	string	yes
userId	string	yes
role	"owner" \	"admin" \	"member"
approvalId	string	no

Example call:

{"name":"add_org_member","arguments":{"orgId":"<orgId>","userId":"<userId>"}}

Related: create_org, set_org_member_role, remove_org_member, set_project_member_role.

create_org

Create an organization as the caller, optionally with an operationId for safe retries. A user token needs orgs.create, no org restriction, and the userTokens.orgAdmin bootstrap-email rollout. The creator becomes owner.

Parameter	Type	Required	Description
name	string	yes
slug	string	no
operationId	string	no
approvalId	string	no

Example call:

{"name":"create_org","arguments":{"name":"<name>"}}

Related: add_org_member, set_org_member_role, remove_org_member.

remove_org_member

Remove a member and their project memberships from an org. User tokens require an org admin/owner, members.manage and data.delete. The last owner cannot leave.

Parameter	Type	Required	Description
orgId	string	yes
userId	string	yes
approvalId	string	no

Example call:

{"name":"remove_org_member","arguments":{"orgId":"<orgId>","userId":"<userId>"}}

Related: create_org, add_org_member, set_org_member_role, set_project_member_role.

set_org_member_role

Change an org member role within your live rank. An owner can grant or revoke ownership; a platform admin may override with a required reason. User tokens need members.manage and platform.admin for an override.

Parameter	Type	Required	Description
orgId	string	yes
userId	string	yes
role	"owner" \	"admin" \	"member"
reason	string	no
approvalId	string	no

Example call:

{"name":"set_org_member_role","arguments":{"orgId":"<orgId>","userId":"<userId>","role":"owner"}}

Related: create_org, add_org_member, remove_org_member, set_project_member_role.

set_project_member_role

Add an org member to a project or change their project role. Requires a PM or org admin/owner; user tokens also require members.manage and userTokens.membership. Every call re-enters REST authorization and auditing.

Parameter	Type	Required	Description
projectId	string	yes
userId	string	yes
role	"pm" \	"developer" \	"tester" \
approvalId	string	no

Example call:

{"name":"set_project_member_role","arguments":{"projectId":"<projectId>","userId":"<userId>","role":"pm"}}

Related: add_org_member, set_org_member_role, remove_org_member.

user_tokens_create

Mint a new user token for the same person, within THIS token's own abilities, org allow-list and expiry (a child can never exceed its parent, and always requires human approval for sensitive actions). Needs the tokens.create_user_tokens ability. Usually answers human_approval_required first: tell the person, wait for approval, then call again with the same arguments plus approvalId. The new token value is in the result ONCE; store it securely and never echo it into chat or tickets.

Parameter	Type	Required	Description
name	string	yes
abilities	string[]	yes	Abilities, e.g. ['read','issues'] (see the user-tokens docs); 'all' only if this token has 'all'.
orgIds	string[]	no	Limit to these org ids (default: this token's own allow-list).
expiresAt	string	no	ISO datetime; default and maximum: this token's own expiry.
agentLabel	string	no
note	string	no
approvalId	string	no	The approvalId from a previous human_approval_required answer, once the person approved it.

Example call:

{"name":"user_tokens_create","arguments":{"name":"<name>","abilities":[]}}

Related: user_tokens_list, user_tokens_revoke.

user_tokens_list

List the user tokens of the person this token acts for: name, prefix, abilities, org allow-list, expiry, approval switch, last use and status. Never returns a token value. Call whoami to see which of them you are.

No parameters.

Example call:

{"name":"user_tokens_list","arguments":{}}

Related: user_tokens_create, user_tokens_revoke.

user_tokens_revoke

Revoke a user token: this token itself or one it minted (and, by default, everything minted below it). Takes effect on the next request. Use it the moment a token may have leaked.

Parameter	Type	Required	Description
tokenId	string	yes	User token id (uuid).
reason	string	no

Example call:

{"name":"user_tokens_revoke","arguments":{"tokenId":"<tokenId>"}}

Related: user_tokens_list, user_tokens_create.