search-users
Search for users in a Descope project by text, email, phone, status, roles, or other filters to manage user access and permissions.
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-166 (handler)The handler function executes the user search using Descope's management.user.search API, handles the response or error, and formats it as MCP content.
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 schema defining the input parameters for the search-users tool, including filters like text, emails, statuses, pagination, etc.
{ // 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-167 (registration)The server.tool call that registers the 'search-users' tool with its name, description, input schema, and handler function.
server.tool( "search-users", "Search for users in 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)"), }, 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}`, }, ], }; } }, );