search-users
Find users in your Descope project by searching text across user fields or filtering by email, phone, status, role, tenant, SSO app, or login ID.
Instructions
Search for users in Descope project
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| text | No | Text to search for in user fields | |
| emails | No | Filter by specific email addresses | |
| phones | No | Filter by specific phone numbers | |
| statuses | No | Filter by user statuses ('enabled', 'disabled', or 'invited') | |
| roles | No | Filter users by role names | |
| tenantIds | No | Filter users by specific tenant IDs | |
| ssoAppIds | No | Filter users by SSO application IDs | |
| loginIds | No | Filter by specific login IDs | |
| withTestUser | No | Include test users in results | |
| testUsersOnly | No | Return only test users | |
| page | No | Page number for pagination | |
| limit | No | Number of users per page (max 100) |
Implementation Reference
- src/descope.ts:131-167 (handler)The handler function that executes the 'search-users' tool. It calls the Descope management.user.search API with the provided filter parameters and returns a formatted text response with the user data or an error message.
async ({ text, emails, phones, statuses, roles, tenantIds, ssoAppIds, loginIds, withTestUser, testUsersOnly, page, limit }) => { try { const users = await descope.management.user.search({ text, emails, phones, statuses, roles, tenantIds, ssoAppIds, loginIds, withTestUser, testUsersOnly, page, limit, }); return { content: [ { type: "text", text: `Found users:\n\n${JSON.stringify(users.data, null, 2)}`, }, ], }; } catch (error) { return { content: [ { type: "text", text: `Error searching users: ${error}`, }, ], }; } }, ); - src/descope.ts:104-130 (schema)Zod input schema defining all parameters for filtering and paginating user searches in the Descope project.
{ // Search parameters text: z.string().optional() .describe("Text to search for in user fields"), emails: z.array(z.string()).optional() .describe("Filter by specific email addresses"), phones: z.array(z.string()).optional() .describe("Filter by specific phone numbers"), statuses: z.array(z.enum(['enabled', 'disabled', 'invited'])).optional() .describe("Filter by user statuses ('enabled', 'disabled', or 'invited')"), roles: z.array(z.string()).optional() .describe("Filter users by role names"), tenantIds: z.array(z.string()).optional() .describe("Filter users by specific tenant IDs"), ssoAppIds: z.array(z.string()).optional() .describe("Filter users by SSO application IDs"), loginIds: z.array(z.string()).optional() .describe("Filter by specific login IDs"), withTestUser: z.boolean().optional() .describe("Include test users in results"), testUsersOnly: z.boolean().optional() .describe("Return only test users"), page: z.number().min(0).optional() .describe("Page number for pagination"), limit: z.number().min(1).max(100).default(10) .describe("Number of users per page (max 100)"), }, - src/descope.ts:101-103 (registration)Registers the 'search-users' tool on the MCP server with its name, description, schema, and handler.
server.tool( "search-users", "Search for users in Descope project",