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 = {