list_auth_users
Retrieve user data from Supabase auth.users table with configurable limit and offset to manage user lists efficiently.
Instructions
Lists users from the auth.users table.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max number of users to return | |
| offset | No | Number of users to skip |
Implementation Reference
- src/tools/list_auth_users.ts:56-94 (handler)The execute handler function that queries the auth.users table using direct PostgreSQL connection, applies limit/offset pagination, and returns validated list of users.execute: async (input: ListAuthUsersInput, context: ToolContext): Promise<ListAuthUsersOutput> => { const client = context.selfhostedClient; const { limit, offset } = input; // Check if direct DB connection is available, as it's likely needed for auth.users if (!client.isPgAvailable()) { context.log('Direct database connection (DATABASE_URL) is required to list auth users.', 'error'); throw new Error('Direct database connection (DATABASE_URL) is required to list auth users.'); } // Construct SQL query - ensure schema name is correct const listUsersSql = ` SELECT id, email, role, raw_app_meta_data, raw_user_meta_data, created_at::text, -- Cast timestamp to text for JSON last_sign_in_at::text -- Cast timestamp to text for JSON FROM auth.users ORDER BY created_at DESC LIMIT ${limit} OFFSET ${offset} `; // No semicolon needed here console.error('Attempting to list auth users using direct DB connection...'); // Use direct connection (executeSqlWithPg) as it likely has necessary privileges const result = await client.executeSqlWithPg(listUsersSql); // Validate and return const validatedUsers = handleSqlResponse(result, ListAuthUsersOutputSchema); console.error(`Found ${validatedUsers.length} users.`); context.log(`Found ${validatedUsers.length} users.`); return validatedUsers; },
- src/tools/list_auth_users.ts:7-28 (schema)Zod schemas for input (limit, offset) and output (array of AuthUser objects with fields like id, email, role, metadata, timestamps).const ListAuthUsersInputSchema = z.object({ limit: z.number().int().positive().optional().default(50).describe('Max number of users to return'), offset: z.number().int().nonnegative().optional().default(0).describe('Number of users to skip'), // Add filters later (e.g., by email pattern, role) }); type ListAuthUsersInput = z.infer<typeof ListAuthUsersInputSchema>; // Output schema - Zod for validation const AuthUserZodSchema = z.object({ id: z.string().uuid(), email: z.string().email().nullable(), role: z.string().nullable(), // Timestamps returned as text from DB might not strictly be ISO 8601 / Zod datetime compliant created_at: z.string().nullable(), last_sign_in_at: z.string().nullable(), raw_app_meta_data: z.record(z.unknown()).nullable(), raw_user_meta_data: z.record(z.unknown()).nullable(), // Add more fields as needed (e.g., email_confirmed_at, phone) }); const ListAuthUsersOutputSchema = z.array(AuthUserZodSchema); // Use AuthUser[] for the output type hint type ListAuthUsersOutput = AuthUser[];
- src/index.ts:113-113 (registration)Registration of the listAuthUsersTool in the availableTools object, which is later used to build MCP capabilities and handle tool calls.[listAuthUsersTool.name]: listAuthUsersTool as AppTool,
- src/types/index.ts:39-52 (schema)TypeScript interface definition for AuthUser, used as the basis for the output schema in list_auth_users tool./** * Represents a user object from the auth.users table. * Based on fields selected in listAuthUsersTool, getAuthUserTool etc. */ export interface AuthUser { id: string; // uuid email: string | null; role: string | null; created_at: string | null; // Timestamps returned as text from DB last_sign_in_at: string | null; raw_app_meta_data: Record<string, unknown> | null; raw_user_meta_data: Record<string, unknown> | null; // Add other relevant fields if needed, e.g., email_confirmed_at }