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

# Users & Roles

> List users and roles; update profiles and team memberships; manage user roles and lifecycle; send and manage invitations.

This group covers everything related to users in your Attention org: listing reps and roles, updating user profiles, changing team memberships, assigning roles, deactivating and reactivating accounts, and managing pending invitations.

Several tools require **user-level authentication** (not org-level API keys) — these are flagged below. The reason is that they perform actions tied to a specific actor (e.g. invitation emails include the inviter's name).

## Read tools

### list\_reps

<Note>Scope: `mcp:read`.</Note>

List all users (reps, managers, admins) in your organization. Optionally filter by email, ID, or team.

<ParamField query="email" type="string">
  Filter by user email address.
</ParamField>

<ParamField query="user_id" type="string">
  Filter by user ID.
</ParamField>

<ParamField query="team_id" type="string">
  Filter by team ID.
</ParamField>

<ParamField query="include_deleted" type="boolean">
  Include soft-deleted (deactivated) users.
</ParamField>

**Returns:** Markdown list of users with names, emails, roles, and team memberships.

***

### list\_roles

<Note>Scope: `mcp:read`. No parameters.</Note>

List all roles defined in your organization with their type (`admin`, `manager`, or `sales_rep`). Use this before assigning roles via `manage_user_role` or `update_user`.

**Returns:** Markdown list of roles with name, type, and UUID.

***

### list\_invitations

<Note>Scope: `mcp:read`.</Note>

List pending invitations in your organization. Shows email, team, role, seat type, and expiration status.

<ParamField query="page" type="integer">
  Page number. Default: `1`.
</ParamField>

<ParamField query="size" type="integer">
  Page size. Default: `20`. Maximum: `50`.
</ParamField>

<ParamField query="email" type="string">
  Filter invitations by email address (exact match).
</ParamField>

<ParamField query="team_id" type="string">
  Filter invitations by team ID.
</ParamField>

## User write tools

### update\_user

<Warning>Scope: `mcp:write`. Requires admin role.</Warning>

Update a user's profile, role, or seat type. Omitted fields preserve current values (read-before-write merge).

<ParamField query="user_id" type="string" required>
  The UUID of the user to update.
</ParamField>

<ParamField query="first_name" type="string">
  New first name.
</ParamField>

<ParamField query="last_name" type="string">
  New last name.
</ParamField>

<ParamField query="role_id" type="string">
  UUID of the role to assign. Use `list_roles` to find role IDs.
</ParamField>

<ParamField query="seat_type" type="string">
  Seat type: `recording` (can record calls) or `listener` (view-only).
</ParamField>

<ParamField query="bot_name" type="string">
  Custom name for the user's recording bot.
</ParamField>

<ParamField query="deals_enabled" type="boolean">
  Whether deal/pipeline features are enabled for this user.
</ParamField>

***

### update\_user\_teams

<Warning>Scope: `mcp:write`. Requires admin role.</Warning>

Add or remove a user from teams in a single operation. Can also set the user's primary team. At least one of `teams_to_add` or `team_ids_to_remove` is required.

<ParamField query="user_id" type="string" required>
  The UUID of the user.
</ParamField>

<ParamField query="teams_to_add" type="array">
  Teams to add the user to. Each entry: `{ "team_id": "...", "primary": false }`. Only one team can be primary.
</ParamField>

<ParamField query="team_ids_to_remove" type="array">
  Team UUIDs to remove the user from.
</ParamField>

## Role and lifecycle tools

### manage\_user\_role

<Warning>Scope: `mcp:write`. Requires admin role.</Warning>

Assign or remove a role for a user. Use `list_roles` to find available role IDs.

<ParamField query="action" type="string" required>
  Action to perform: `set` to assign, `remove` to remove.
</ParamField>

<ParamField query="user_id" type="string" required>
  UUID of the user.
</ParamField>

<ParamField query="role_id" type="string" required>
  UUID of the role.
</ParamField>

***

### delete\_user

<Warning>Scope: `mcp:write`. Requires admin role and **user-level authentication** (org-level API keys are not supported). Destructive but reversible via `reactivate_user`.</Warning>

Soft-delete (deactivate) a user. The user loses access immediately but can be reactivated later. Their team memberships are preserved.

<ParamField query="user_id" type="string" required>
  UUID of the user to deactivate.
</ParamField>

***

### reactivate\_user

<Warning>Scope: `mcp:write`. Requires admin role.</Warning>

Reactivate a previously deactivated user. Restores their access and team memberships.

<ParamField query="user_id" type="string" required>
  UUID of the user to reactivate.
</ParamField>

## Invitation tools

### invite\_user

<Warning>Scope: `mcp:write`. Requires admin role and **user-level authentication** (org-level API keys are not supported — the invitation email includes the inviter's name).</Warning>

Invite a user to your organization by email. The recipient receives an email invitation to join the specified team with the given role.

<ParamField query="email" type="string" required>
  Email address of the user to invite.
</ParamField>

<ParamField query="role_id" type="string" required>
  Role UUID to assign. Use `list_roles` to get available role IDs.
</ParamField>

<ParamField query="team_id" type="string" required>
  Team UUID to add the user to. Use [`list_teams`](/mcp/tools/teams#list_teams) to get available team IDs.
</ParamField>

<ParamField query="seat_type" type="string" required>
  Seat type: `listener` (view-only) or `recording` (can record calls).
</ParamField>

***

### update\_invitation

<Warning>Scope: `mcp:write`. Requires admin role and **user-level authentication**.</Warning>

Update a pending invitation's seat type. Only pending (not yet accepted) invitations can be updated.

<ParamField query="invitation_id" type="string" required>
  UUID of the invitation to update.
</ParamField>

<ParamField query="seat_type" type="string" required>
  New seat type: `listener` or `recording`.
</ParamField>

***

### delete\_invitation

<Warning>Scope: `mcp:write`. Requires admin role and **user-level authentication**. Destructive.</Warning>

Delete a pending invitation. Only pending (not yet accepted) invitations can be deleted.

<ParamField query="invitation_id" type="string" required>
  UUID of the invitation to delete.
</ParamField>