> For the complete documentation index, see [llms.txt](https://support.attackforge.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.attackforge.com/app/modules/ai-mcp-and-skills/find-users.md).
# 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_` | value of the user custom field ``. 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
{% code overflow="wrap" %}
```json
{
"data": [
{
"id": "65a440c08cade68ca7bc7192",
"created": "2024-01-15T02:11:44.000Z",
"modified": "2026-08-30T23:02:17.000Z",
"first_name": "Jane",
"last_name": "Smith",
"email": "jane.smith@example.com",
"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
}
```
{% endcode %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://support.attackforge.com/app/modules/ai-mcp-and-skills/find-users.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.