> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcpmanager.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# People, Teams & Roles

> Admin API operations for people: invite and deactivate users, assign roles and teams, and create, modify, list, and delete roles and teams.

These operations manage the people in your workspace and the roles and teams that scope what they can do. User and role operations each require their own management capability.

<Info>
  **Closed beta.** The MCP Manager Admin API and MCP server are available now to a
  limited set of workspaces through the **MCP Manager Admin API** entitlement
  (`ff-mcpm-admin`), ahead of general availability. If you don't see **Settings →
  MCP & API** in your workspace, it isn't enabled for you yet — ask your MCP Manager
  contact to join the beta.
</Info>

## List Teams

<Badge color="green">Read-only</Badge>

List the workspace’s teams.

Returns each accessible team as `{ guid, name, enabled }`, scoped to what the caller may see, like the people → teams page.

**MCP tool:** `list_teams` · **REST:** `GET /api/v1/mcpm-admin/teams` · **Capability:** none — available to any authenticated caller

**Parameters:** none.

**Example**

```json theme={null}
{}
```

## Create Team

Create a workspace team.

Creates an enabled team owned by the caller (a `creator` edge), wired to the organization. Returns `{ guid, name, enabled }`. Add members with set\_user\_teams and provision gateways with assign\_team\_to\_gateway.

**MCP tool:** `create_team` · **REST:** `POST /api/v1/mcpm-admin/teams` · **Capability:** Manage teams (`manageTeams`)

**Parameters**

<ParamField body="name" type="string" required>
  A human-readable name for the team (e.g. "Engineering").
</ParamField>

**Example**

```json theme={null}
{"name":"Engineering"}
```

## Rename Team

Rename a team.

Renames the team. Saved only when the name actually changes. Returns `{ guid, name, enabled }`.

**MCP tool:** `rename_team` · **REST:** `PATCH /api/v1/mcpm-admin/teams/:teamGuid/name` · **Capability:** Manage teams (`manageTeams`)

**Parameters**

<ParamField path="teamGuid" type="string" required>
  The guid of the team to rename (from list\_teams).
</ParamField>

<ParamField body="newName" type="string" required>
  The new name for the team.
</ParamField>

**Example**

```json theme={null}
{"teamGuid":"WST-...","newName":"Platform"}
```

## Delete Team

<Badge color="red">Destructive</Badge>

Delete a team.

Hard-deletes the team; its membership and gateway-provisioning edges are removed. Returns `{ deleted: true, teamGuid }`.

**MCP tool:** `delete_team` · **REST:** `DELETE /api/v1/mcpm-admin/teams/:teamGuid` · **Capability:** Manage teams (`manageTeams`)

**Parameters**

<ParamField path="teamGuid" type="string" required>
  The guid of the team to delete (from list\_teams).
</ParamField>

**Example**

```json theme={null}
{"teamGuid":"WST-..."}
```

## List Roles

<Badge color="green">Read-only</Badge>

List the workspace’s roles.

Returns each role as `{ guid, name, grantedCapabilities }`, where `grantedCapabilities` are the capability keys the role grants (value true) — the same keys whoami reports for a user.

**MCP tool:** `list_roles` · **REST:** `GET /api/v1/mcpm-admin/roles` · **Capability:** Manage roles (`manageRoles`)

**Parameters:** none.

**Example**

```json theme={null}
{}
```

## Create Role

Create a workspace role.

Creates a role owned by the caller, wired to the organization, with the given capability grants (empty by default). Returns `{ guid, name, grantedCapabilities }`.

**MCP tool:** `create_role` · **REST:** `POST /api/v1/mcpm-admin/roles` · **Capability:** Manage roles (`manageRoles`)

**Parameters**

<ParamField body="name" type="string" required>
  A human-readable name for the role (e.g. "Gateway Operator").
</ParamField>

<ParamField body="grants" type="object">
  Initial capability grants as a map of capability key → "true"/"false" (e.g. `{ "basicGatewayManagement": "true" }`). Omit to create a role with no capabilities (set them later with modify\_role). Any value other than "true" is treated as false. *(a string → string map)*
</ParamField>

**Example**

```json theme={null}
{"name":"Viewer"}
```

## Modify Role

Rename a role and/or change its capability grants.

Updates the role’s name and/or merges the supplied capability grants into its existing grants (provided keys are set; others unchanged). Saved only when something actually changes. Returns `{ guid, name, grantedCapabilities }`.

**MCP tool:** `modify_role` · **REST:** `PATCH /api/v1/mcpm-admin/roles/:roleGuid` · **Capability:** Manage roles (`manageRoles`)

**Parameters**

<ParamField path="roleGuid" type="string" required>
  The guid of the role to modify (from list\_roles).
</ParamField>

<ParamField body="name" type="string">
  A new name for the role.
</ParamField>

<ParamField body="grants" type="object">
  Capability grants to set, as a map of capability key → "true"/"false". MERGED into the existing grants — only the provided keys change; others are left as-is. Any value other than "true" is treated as false. *(a string → string map)*
</ParamField>

**Example**

```json theme={null}
{"roleGuid":"WSR-...","grants":{"deleteServers":"true"}}
```

## Delete Role

<Badge color="red">Destructive</Badge>

Delete a role, reassigning its users to a replacement role.

Before deleting, every user currently on the role is moved to `reassignToRoleGuid` (so no user is ever left without a role), then the role is deleted. Returns `{ deleted: true, reassignedUsers }`.

**MCP tool:** `delete_role` · **REST:** `DELETE /api/v1/mcpm-admin/roles/:roleGuid` · **Capability:** Manage roles (`manageRoles`)

**Parameters**

<ParamField path="roleGuid" type="string" required>
  The guid of the role to delete (from list\_roles).
</ParamField>

<ParamField query="reassignToRoleGuid" type="string" required>
  The guid of the role to move every affected user onto. Required — a user must always have exactly one role.
</ParamField>

**Example**

```json theme={null}
{"roleGuid":"WSR-old","reassignToRoleGuid":"WSR-new"}
```

## List Users

<Badge color="green">Read-only</Badge>

List the workspace’s users with their role and teams.

Returns each user as `{ guid, emailAddress, displayName, isActive, roleGuid, roleName, teamGuids }`, scoped to what the caller may see, like the people → users page.

**MCP tool:** `list_users` · **REST:** `GET /api/v1/mcpm-admin/users` · **Capability:** none — available to any authenticated caller

**Parameters:** none.

**Example**

```json theme={null}
{}
```

## Set User Role

Set a user’s role.

Assigns the role to the user, replacing their current one (a user has exactly one role). Returns the updated user `{ guid, emailAddress, displayName, isActive, roleGuid, roleName, teamGuids }`.

**MCP tool:** `set_user_role` · **REST:** `PUT /api/v1/mcpm-admin/users/:userGuid/role` · **Capability:** Manage user role assignments (`manageUserRoles`)

**Parameters**

<ParamField path="userGuid" type="string" required>
  The guid of the user (from list\_users).
</ParamField>

<ParamField body="roleGuid" type="string" required>
  The guid of the role to assign (from list\_roles).
</ParamField>

**Example**

```json theme={null}
{"userGuid":"USR-...","roleGuid":"WSR-..."}
```

## Set User Teams

Replace a user’s team memberships.

Sets the user’s teams to exactly the provided list: missing memberships are added, ones not listed are removed. Returns the updated user `{ guid, emailAddress, displayName, isActive, roleGuid, roleName, teamGuids }`.

**MCP tool:** `set_user_teams` · **REST:** `PUT /api/v1/mcpm-admin/users/:userGuid/teams` · **Capability:** Manage user team assignments (`manageUserTeams`)

**Parameters**

<ParamField path="userGuid" type="string" required>
  The guid of the user (from list\_users).
</ParamField>

<ParamField body="teamGuids" type="string" required>
  The full set of team guids the user should belong to, comma-separated (e.g. "WST-a,WST-b"). This REPLACES the user’s team memberships — teams not listed are removed. Pass an empty string to clear all.
</ParamField>

**Example**

```json theme={null}
{"userGuid":"USR-...","teamGuids":"WST-a,WST-b"}
```

## Invite User

Invite a new user to the workspace.

Sends a workspace invitation, optionally assigning a role and teams. The invite is processed through the BFF so role/team edges and notification wiring are created correctly. Returns `{ email, userGuid }` (`userGuid` is the created user once available). The caller is recorded as the referrer.

**MCP tool:** `invite_user` · **REST:** `POST /api/v1/mcpm-admin/users/invite` · **Capability:** Invite users (`inviteUsers`)

**Parameters**

<ParamField body="email" type="string" required>
  The email address to invite.
</ParamField>

<ParamField body="firstName" type="string">
  The invitee’s first name (optional).
</ParamField>

<ParamField body="lastName" type="string">
  The invitee’s last name (optional).
</ParamField>

<ParamField body="roleGuid" type="string">
  The guid of the role to assign the invitee (from list\_roles).
</ParamField>

<ParamField body="teamGuids" type="string">
  Comma-separated team guids to add the invitee to (from list\_teams), e.g. "WST-a,WST-b".
</ParamField>

<ParamField body="message" type="string">
  An optional custom message included in the invitation email.
</ParamField>

**Example**

```json theme={null}
{"email":"new@example.com","roleGuid":"WSR-...","teamGuids":"WST-..."}
```

## Deactivate User

<Badge color="red">Destructive</Badge>

Deactivate a workspace user.

Deactivates the user (removes their workspace membership and license) via the BFF. Authorization is enforced by the `removeUsers` capability. Returns `{ deactivated: <userGuid> }`.

**MCP tool:** `deactivate_user` · **REST:** `POST /api/v1/mcpm-admin/users/:userGuid/deactivate` · **Capability:** Remove users (`removeUsers`)

**Parameters**

<ParamField path="userGuid" type="string" required>
  The guid of the user to deactivate (from list\_users).
</ParamField>

**Example**

```json theme={null}
{"userGuid":"USR-..."}
```

## Further reading

<CardGroup cols={2}>
  <Card title="Hosts" icon="arrow-right" href="/admin-api/reference/hosts">
    Where to go next in this section.
  </Card>

  <Card title="Authentication & access" icon="shield-halved" href="/admin-api/authentication">
    Tokens, the entitlement, capability gating, and error codes for every operation here.
  </Card>

  <Card title="Tool & endpoint reference" icon="book" href="/admin-api/reference/overview">
    The full reference index across every domain.
  </Card>

  <Card title="Capabilities" icon="key" href="/deployment/rbac-and-roles/capabilities">
    What each capability named on this page actually allows.
  </Card>
</CardGroup>