Okta MCP Server

Instructions

Implementation Reference

• src/tools/users.ts:424-520 (handler)

  The main handler function for the 'list_users' tool. It validates input parameters using Zod schema, constructs query parameters for the Okta API, fetches the list of users, iterates through them using a for-await loop, formats a detailed text response including user details and pagination info, and returns the content in the expected MCP format.
  list_users: async (request: { parameters: unknown }) => { const params = userSchemas.listUsers.parse(request.parameters); try { // Build query parameters const queryParams: Record<string, any> = {}; if (params.limit) queryParams.limit = params.limit; if (params.after) queryParams.after = params.after; if (params.filter) queryParams.filter = params.filter; if (params.search) queryParams.search = params.search; if (params.sortBy) queryParams.sortBy = params.sortBy; if (params.sortOrder) queryParams.sortOrder = params.sortOrder; const oktaClient = getOktaClient(); // Get users list const users = await oktaClient.userApi.listUsers(queryParams); if (!users) { return { content: [ { type: "text", text: "No users data was returned from Okta.", }, ], }; } // Format the response let formattedResponse = "Users:\n"; let count = 0; // Track pagination info let after: string | undefined; // Process the users collection for await (const user of users) { // Check if user is valid if (!user || !user.id) { continue; } count++; // Remember the last user ID for pagination after = user.id; formattedResponse += ` ${count}. ${user.profile?.firstName || ""} ${user.profile?.lastName || ""} (${user.profile?.email || "No email"}) - ID: ${user.id} - Status: ${user.status || "Unknown"} - Created: ${formatDate(user.created)} - Last Updated: ${formatDate(user.lastUpdated)} `; } if (count === 0) { return { content: [ { type: "text", text: "No users found matching your criteria.", }, ], }; } // Add pagination information if (after && count >= (params.limit || 50)) { formattedResponse += `\nPagination:\n- Total users shown: ${count}\n`; formattedResponse += `- For next page, use 'after' parameter with value: ${after}\n`; } else { formattedResponse += `\nTotal users: ${count}\n`; } return { content: [ { type: "text", text: formattedResponse, }, ], }; } catch (error) { console.error("Error listing users:", error); return { content: [ { type: "text", text: `Failed to list users: ${error instanceof Error ? error.message : String(error)}`, }, ], isError: true, }; } },
• src/tools/users.ts:19-26 (schema)

  Zod schema definition for validating the input parameters of the list_users tool, used in the handler for parsing request.parameters.
  listUsers: z.object({ limit: z.number().min(1).max(200).optional().default(50), filter: z.string().optional(), search: z.string().optional(), after: z.string().optional(), sortBy: z.string().optional(), sortOrder: z.enum(["asc", "desc"]).optional().default("asc"), }),
• src/tools/users.ts:184-218 (registration)

  The tool registration object in the userTools export array, defining the name 'list_users', description, and JSON inputSchema for MCP tool registration.
  { name: "list_users", description: "List users from Okta with optional filtering and pagination", inputSchema: { type: "object", properties: { limit: { type: "number", description: "Maximum number of users to return (default: 50, max: 200)", }, filter: { type: "string", description: "SCIM filter expression to filter users", }, search: { type: "string", description: "Free-form text search across multiple fields", }, after: { type: "string", description: "Cursor for pagination, obtained from previous response", }, sortBy: { type: "string", description: "Field to sort results by", }, sortOrder: { type: "string", description: "Sort order (asc or desc, default: asc)", enum: ["asc", "desc"], }, }, }, },