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,
    });
  }