Find Users

Description

Lists AttackForge users matching the optional filter. Use this to resolve the user ids that appear on other records (a project's team, a vulnerability's author, an assignee) into names, email addresses and account state - call count_users when only a total is needed. Deleted users are excluded unless include_deleted is set. Results are paginated (default 10 per page, max 50).

What is returned depends on who is calling:

• Administrators see every user and every field.

• Any other caller silently gets only their own user record, with a reduced set of fields: id, created, modified, first_name, last_name, email, username, role, status, mfa_enabled, last_logged_in, last_login_type and profile. Other fields values are dropped rather than rejected.

Custom-field values are requested separately via custom_field_keys and are returned to every caller, subject to the tenant's per-role custom-field access.

How To Enable

1. Go to Users

2. Select the user you would like to provide access to this tool

3. Click on Access > MCP

4. Click on Add Tools

5. Select the tool find_users and click Add

Example Prompts

• Who is the user with id 65a440c08cade68ca7bc7192?

• List all the consultants with their email addresses.

• Which users have not logged in since January?

• Show me the blocked accounts.

• Find users with "smith" in their last name.

• Who is in the Security department? Include the department custom field.

• Show me the deleted users so I can restore one.

Parameters

Parameter	Type	Required	Description
filter	object	No	A MongoDB-style filter. Supported fields are listed below.
fields	array	No	System fields to include on each user (id is always returned). Supported values are listed below. Fields the caller may not see are dropped rather than rejected.
custom_field_keys	array	No	Custom field keys to include (discover via get_field_structure(model="user")). Keys the caller is not permitted to view are dropped rather than rejected.
include_deleted	boolean	No	Include users that have been deleted. Defaults to false. Administrators only - ignored for any other caller. Combine with the is_deleted filter field to list only the deleted users, and pair it with restore_user to bring one back.
limit	integer	No	Maximum records to return in this page. Default 10, max 50.
skip	integer	No	Number of records to skip (offset). Default 0.

Supported filter fields (any caller):

Field	Type / Values
id	ObjectId('<24 hex>')
email	string
first_name, last_name	string
username	string
custom_field_<key>	value of the user custom field <key>. Only keys configured to display in tables and viewable by the caller are accepted; discover keys via get_field_structure(model="user")

Supported filter fields (administrators only - anyone else is rejected):

Field	Type / Values
created, modified	ISO-8601 datetime
account_expiry	ISO-8601 datetime
email_verified	boolean
exempt_global_inactivity_policy	boolean
failed_logins	integer
force_password_change	boolean
is_deleted	boolean
last_active_on_app, last_active_on_ssapi	ISO-8601 datetime
last_logged_in	ISO-8601 datetime
last_login_type	one of 'local', 'sso'
mfa_enabled	boolean
role	one of 'admin', 'projectoperator', 'librarymod', 'consultant', 'client'
status	one of 'Active', 'Blocked', 'Invited'

Any other field is rejected. profile is returnable but not filterable. A caller who is not an administrator is always restricted to their own user record, whatever the filter says.

mfa_enabled is on for a user unless it has been explicitly set to false - users where it has never been set have it enabled. Matching on true covers both, so { mfa_enabled: { $eq: true } } needs no special handling.

Supported fields values:

Field	Type
id	string
created, modified	ISO-8601 datetime
first_name, last_name	string
email	string
username	string
role	string
status	string
last_login_type	string - local or sso
mfa_enabled	boolean - defaults to true when it has never been set
last_logged_in	ISO-8601 datetime
profile	object - job_title, organization, business_group, office_location, about_me, tags, certifications, education, employment. Absent when the profile is empty.
is_deleted	boolean. Administrators only.
last_active_on_app, last_active_on_ssapi	ISO-8601 datetime. Administrators only.
account_expiry	ISO-8601 datetime. Absent when the account does not expire. Administrators only.
failed_logins	integer. Administrators only.
email_verified	boolean. Administrators only.
force_password_change	boolean. Administrators only.
exempt_global_inactivity_policy	boolean. Administrators only.

Example Response

{
  "data": [
    {
      "id": "65a440c08cade68ca7bc7192",
      "created": "2024-01-15T02:11:44.000Z",
      "modified": "2026-08-30T23:02:17.000Z",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "[e-mail]",
      "username": "jsmith",
      "role": "consultant",
      "status": "Active",
      "last_login_type": "sso",
      "mfa_enabled": true,
      "last_logged_in": "2026-09-01T08:14:02.000Z",
      "profile": {
        "job_title": "Senior Penetration Tester",
        "organization": "ACME Security",
        "tags": [
          "web",
          "mobile"
        ],
        "certifications": [
          "OSCP"
        ]
      },
      "custom_fields": [
        {
          "key": "department",
          "value": "Security",
          "label": "Department"
        }
      ]
    }
  ],
  "count": 1,
  "total": 1
}