Okta MCP Server

Instructions

Implementation Reference

• src/tools/onboarding.ts:502-602 (handler)

  The handler function for 'run_onboarding_workflow' that orchestrates bulk user import, group assignments based on attributes, and application provisioning from CSV data.

    run_onboarding_workflow: async (request: { parameters: unknown }) => {
      const {
        csvData,
        activateUsers,
        defaultGroups,
        groupMappings,
        applicationIds,
        sendWelcomeEmail
      } = onboardingSchemas.runOnboardingWorkflow.parse(request.parameters);
      
      try {
        // Step 1: Import users
        const importResults = await onboardingHandlers.bulk_user_import({
          parameters: {
            csvData,
            activateUsers,
            sendEmail: sendWelcomeEmail,
            defaultGroups
          }
        });
        
        if (!importResults.data || !importResults.data.success || importResults.data.success.length === 0) {
          return {
            content: [{ type: 'text', text: 'No users were successfully created during the onboarding workflow.' }],
            data: { userImport: importResults.data }
          };
        }
        
        const createdUserIds = importResults.data.success.map((user: any) => user.id);
        
        // Step 2: Assign to groups based on attributes (if mappings provided)
        let groupResults: any = { data: { success: [], failed: [] } };
        if (Object.keys(groupMappings).length > 0) {
          groupResults = await onboardingHandlers.assign_users_to_groups({
            parameters: {
              userIds: createdUserIds,
              attributeMapping: groupMappings
            }
          });
        }
        
        // Step 3: Provision applications (if any provided)
        let appResults: any = { data: { success: [], failed: [] } };
        if (applicationIds.length > 0) {
          appResults = await onboardingHandlers.provision_applications({
            parameters: {
              userIds: createdUserIds,
              applicationIds
            }
          });
        }
        
        // Compile workflow results
        const workflow = {
          userImport: importResults.data,
          groupAssignment: groupResults.data,
          applicationProvisioning: appResults.data,
          summary: {
            totalProcessed: importResults.data.success.length + importResults.data.failed.length,
            successfullyOnboarded: importResults.data.success.length,
            failedUsers: importResults.data.failed.length,
            groupsAssigned: groupResults.data.success.length,
            applicationsProvisioned: appResults.data.success.length
          }
        };
        
        // Format response with detailed summary
        const summary = `Onboarding Workflow Complete:
  
  - User Import:
    - Processed ${workflow.summary.totalProcessed} users
    - Successfully created: ${workflow.summary.successfullyOnboarded}
    - Failed: ${workflow.summary.failedUsers}
  
  ${Object.keys(groupMappings).length > 0 ? `• Group Assignment:
    - Users assigned to groups: ${workflow.groupAssignment.success.length}
    - Failed group assignments: ${workflow.groupAssignment.failed.length}` : '• Group Assignment: Not configured'}
  
  ${applicationIds.length > 0 ? `• Application Provisioning:
    - Users provisioned with applications: ${workflow.applicationProvisioning.success.length}
    - Failed application provisioning: ${workflow.applicationProvisioning.failed.length}` : '• Application Provisioning: Not configured'}
  
  Overall, successfully onboarded ${workflow.summary.successfullyOnboarded} out of ${workflow.summary.totalProcessed} users with ${Object.keys(groupMappings).length > 0 ? 'attribute-based group assignment' : 'default groups only'} and ${applicationIds.length > 0 ? 'application provisioning' : 'no application provisioning'}.`;
        
        return {
          content: [{ type: 'text', text: summary }],
          data: workflow
        };
      } catch (error) {
        console.error("Error during onboarding workflow:", error);
        return {
          content: [
            {
              type: "text",
              text: `Failed to complete onboarding workflow: ${error instanceof Error ? error.message : String(error)}`,
            },
          ],
          isError: true,
        };
      }
    }

• src/tools/onboarding.ts:27-34 (schema)

  Zod schema definition for validating the input parameters of runOnboardingWorkflow.

  runOnboardingWorkflow: z.object({
    csvData: z.string().min(1, "CSV data is required"),
    activateUsers: z.boolean().optional().default(true),
    defaultGroups: z.array(z.string()).optional().default([]),
    groupMappings: z.record(z.record(z.string())).optional().default({}),
    applicationIds: z.array(z.string()).optional().default([]),
    sendWelcomeEmail: z.boolean().optional().default(true),
  }),

• src/tools/onboarding.ts:131-171 (registration)

  Tool registration entry in the onboardingTools array, including name, description, and JSON input schema.

  {
    name: "run_onboarding_workflow",
    description: "Run a complete onboarding workflow for multiple users from CSV data",
    inputSchema: {
      type: "object",
      properties: {
        csvData: {
          type: "string",
          description: "CSV string with user information"
        },
        activateUsers: {
          type: "boolean",
          description: "Whether to activate users immediately (default: true)",
          default: true
        },
        defaultGroups: {
          type: "array",
          items: { type: "string" },
          description: "Default group IDs to assign all users to",
          default: []
        },
        groupMappings: {
          type: "object", 
          description: "Mapping of user attributes to group IDs (e.g., {\"department\": {\"Engineering\": \"group1Id\"}})",
          default: {}
        },
        applicationIds: {
          type: "array",
          items: { type: "string" },
          description: "Application IDs to provision for all users",
          default: []
        },
        sendWelcomeEmail: {
          type: "boolean",
          description: "Whether to send welcome emails (default: true)",
          default: true
        }
      },
      required: ["csvData"]
    },
  }