Okta MCP Server

Instructions

Implementation Reference

• src/tools/onboarding.ts:290-393 (handler)

  The main handler function for the 'assign_users_to_groups' tool. It parses input, fetches user profiles from Okta, matches attributes to group mappings, assigns users to corresponding groups using Okta API, and returns a detailed summary of successes and failures.

    assign_users_to_groups: async (request: { parameters: unknown }) => {
      const { userIds, attributeMapping } = 
        onboardingSchemas.assignUsersToGroups.parse(request.parameters);
      
      try {
        const oktaClient = getOktaClient();
        
        const results = {
          success: [] as any[],
          failed: [] as any[]
        };
        
        // Process each user
        for (const userId of userIds) {
          try {
            // Get user details to access attributes
            const user = await oktaClient.userApi.getUser({ userId });
            
            if (!user || !user.profile) {
              results.failed.push({
                userId: userId,
                reason: 'User not found or profile unavailable'
              });
              continue;
            }
            
            // Determine which groups to assign based on user attributes
            const groupsToAssign = new Set<string>();
            
            // Process attribute mapping
            for (const [attribute, valueMapping] of Object.entries(attributeMapping)) {
              const userAttributeValue = user.profile[attribute as keyof typeof user.profile];
              if (userAttributeValue && valueMapping[userAttributeValue as string]) {
                groupsToAssign.add(valueMapping[userAttributeValue as string]);
              }
            }
            
            // Skip if no groups matched
            if (groupsToAssign.size === 0) {
              results.success.push({
                id: userId,
                email: user.profile.email,
                assignedGroups: [],
                message: 'No group mappings matched user attributes'
              });
              continue;
            }
            
            // Assign user to each mapped group
            const assignedGroups = [];
            for (const groupId of groupsToAssign) {
              await oktaClient.groupApi.assignUserToGroup({
                groupId,
                userId
              });
              assignedGroups.push(groupId);
            }
            
            results.success.push({
              userId: userId,
              email: user.profile.email,
              assignedGroups
            });
          } catch (error) {
            results.failed.push({
              id: userId,
              reason: error instanceof Error ? error.message : String(error)
            });
          }
        }
        
        // Format response
        const summary = `Processed group assignments for ${userIds.length} users:
  - Successful assignments: ${results.success.length}
  - Failed assignments: ${results.failed.length}
  
  ${results.success.length > 0 ? `• Successfully assigned users:
  ${results.success.map((user, i) => {
    const groupsInfo = user.assignedGroups.length > 0 
      ? `assigned to ${user.assignedGroups.length} groups`
      : user.message || 'no matching groups';
    return `${i+1}. ${user.email || user.userId} (${groupsInfo})`;
  }).join('\n')}` : ''}
  
  ${results.failed.length > 0 ? `• Failed assignments:
  ${results.failed.map((user, i) => `${i+1}. User ID: ${user.userId} - ${user.reason}`).join('\n')}` : ''}`;
        
        return {
          content: [{ type: 'text', text: summary }],
          data: results
        };
      } catch (error) {
        console.error("Error during group assignment:", error);
        return {
          content: [
            {
              type: "text",
              text: `Failed to assign users to groups: ${error instanceof Error ? error.message : String(error)}`,
            },
          ],
          isError: true,
        };
      }
    },

• src/tools/onboarding.ts:15-20 (schema)

  Zod schema used for internal input validation within the handler of the 'assign_users_to_groups' tool.

  assignUsersToGroups: z.object({
    userIds: z.array(z.string().min(1, "User ID is required")),
    attributeMapping: z.record(z.record(z.string())).describe(
      "Mapping of user attributes to group IDs (e.g., {\"department\": {\"Engineering\": \"group1Id\"}})"
    ),
  }),

• src/tools/onboarding.ts:93-110 (registration)

  Tool registration object defining the name, description, and input schema for the 'assign_users_to_groups' tool, included in the onboardingTools export which is aggregated into the main TOOLS array.

    name: "assign_users_to_groups",
    description: "Assign multiple users to groups based on attributes",
    inputSchema: {
      type: "object",
      properties: {
        userIds: {
          type: "array",
          items: { type: "string" },
          description: "List of user IDs to assign"
        },
        attributeMapping: {
          type: "object",
          description: "Mapping of user attributes to group IDs (e.g., {\"department\": {\"Engineering\": \"group1Id\", \"Sales\": \"group2Id\"}})"
        }
      },
      required: ["userIds", "attributeMapping"]
    },
  },

• src/tools/index.ts:6-6 (registration)

  Aggregation of all tools including onboardingTools (which contains 'assign_users_to_groups') into the main TOOLS export used by the MCP server.

  export const TOOLS = [...userTools, ...groupTools, ...onboardingTools];

• src/tools/index.ts:9-9 (registration)

  Aggregation of all handlers including onboardingHandlers (which contains the handler for 'assign_users_to_groups') into the main HANDLERS export used by the MCP server.

  export const HANDLERS = {