Okta MCP Server

Instructions

Implementation Reference

• src/tools/groups.ts:540-635 (handler)

  The main handler function for the 'list_group_users' tool. It validates input parameters using Zod, retrieves the Okta client, calls the Okta API to list users in the specified group with pagination support, formats the user list into a readable text response, and handles errors.
  list_group_users: async (request: { parameters: unknown }) => { const params = groupSchemas.listGroupUsers.parse(request.parameters); try { const oktaClient = getOktaClient(); // Build query parameters for pagination const queryParams: Record<string, any> = {}; if (params.limit) queryParams.limit = params.limit; if (params.after) queryParams.after = params.after; // Get group users list const users = await oktaClient.groupApi.listGroupUsers({ groupId: params.groupId, ...queryParams, }); if (!users) { return { content: [ { type: "text", text: "No users data was returned from Okta.", }, ], }; } // Format the response let formattedResponse = `Users in Group (ID: ${params.groupId}):\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 in this group.", }, ], }; } // 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 in group: ${count}\n`; } return { content: [ { type: "text", text: formattedResponse, }, ], }; } catch (error) { console.error("Error listing group users:", error); return { content: [ { type: "text", text: `Failed to list group users: ${error instanceof Error ? error.message : String(error)}`, }, ], isError: true, }; } },
• src/tools/groups.ts:39-43 (schema)

  Zod schema for input validation of the 'list_group_users' tool parameters, used in the handler to parse and validate the request.parameters.
  listGroupUsers: z.object({ groupId: z.string().min(1, "Group ID is required"), limit: z.number().min(1).max(200).optional().default(50), after: z.string().optional(), }),
• src/tools/groups.ts:212-234 (registration)

  Tool registration entry in the groupTools array, defining the name, description, and JSON inputSchema for the MCP tool 'list_group_users'.
  { name: "list_group_users", description: "List all users in a specific group", inputSchema: { type: "object", properties: { groupId: { type: "string", description: "ID of the group", }, limit: { type: "number", description: "Maximum number of users to return (default: 50, max: 200)", }, after: { type: "string", description: "Cursor for pagination, obtained from previous response", }, }, required: ["groupId"], }, },
• src/tools/groups.ts:47-67 (helper)

  Utility function to initialize and return the Okta client instance, used by the handler to make API calls.
  function getOktaClient() { const oktaDomain = process.env.OKTA_ORG_URL; const apiToken = process.env.OKTA_API_TOKEN; if (!oktaDomain) { throw new Error( "OKTA_ORG_URL environment variable is not set. Please set it to your Okta domain." ); } if (!apiToken) { throw new Error( "OKTA_API_TOKEN environment variable is not set. Please generate an API token in the Okta Admin Console." ); } return new OktaClient({ orgUrl: oktaDomain, token: apiToken, }); }