Okta MCP Server

Instructions

Implementation Reference

• src/tools/onboarding.ts:395-500 (handler)

  The main handler function for the 'provision_applications' tool. It validates input with Zod, uses Okta SDK to assign users to applications, tracks success/failure per user and per app, and returns a formatted summary.

    provision_applications: async (request: { parameters: unknown }) => {
      const { userIds, applicationIds } = 
        onboardingSchemas.provisionApplications.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
            const user = await oktaClient.userApi.getUser({ userId });
            
            if (!user || !user.profile) {
              results.failed.push({
                userId,
                reason: 'User not found or profile unavailable'
              });
              continue;
            }
            
            const userResults = {
              userId,
              email: user.profile.email,
              applications: [] as any[]
            };
            
            let hasFailure = false;
            
            // Assign each application
            for (const appId of applicationIds) {
              try {
                // Assign user to application
                await oktaClient.applicationApi.assignUserToApplication({
                  appId,
                  appUser: {
                    id: userId
                  }
                });
                
                userResults.applications.push({
                  appId,
                  status: 'assigned'
                });
              } catch (error) {
                hasFailure = true;
                userResults.applications.push({
                  appId,
                  status: 'failed',
                  reason: error instanceof Error ? error.message : String(error)
                });
              }
            }
            
            if (hasFailure) {
              results.failed.push(userResults);
            } else {
              results.success.push(userResults);
            }
          } catch (error) {
            results.failed.push({
              userId,
              reason: error instanceof Error ? error.message : String(error),
              applications: []
            });
          }
        }
        
        // Format response
        const summary = `Processed application provisioning for ${userIds.length} users across ${applicationIds.length} applications:
  - Successful provisioning: ${results.success.length} users
  - Failed provisioning: ${results.failed.length} users
  
  ${results.success.length > 0 ? `• Successfully provisioned users:
  ${results.success.map((user, i) => 
    `${i+1}. ${user.email || user.userId} (provisioned ${user.applications.length} applications)`
  ).join('\n')}` : ''}
  
  ${results.failed.length > 0 ? `• Failed provisioning:
  ${results.failed.map((user, i) => {
    const failedApps = user.applications.filter((app: { status: string; }) => app.status === 'failed').length;
    return `${i+1}. ${user.email || user.userId} - ${user.reason || `${failedApps} applications failed`}`;
  }).join('\n')}` : ''}`;
        
        return {
          content: [{ type: 'text', text: summary }],
          data: results
        };
      } catch (error) {
        console.error("Error during application provisioning:", error);
        return {
          content: [
            {
              type: "text",
              text: `Failed to provision applications: ${error instanceof Error ? error.message : String(error)}`,
            },
          ],
          isError: true,
        };
      }
    },

• src/tools/onboarding.ts:111-130 (registration)

  The tool registration in the onboardingTools array, including name, description, and JSON inputSchema for the MCP tool.

  {
    name: "provision_applications",
    description: "Provision application access for multiple users",
    inputSchema: {
      type: "object",
      properties: {
        userIds: {
          type: "array",
          items: { type: "string" },
          description: "List of user IDs to provision access for"
        },
        applicationIds: {
          type: "array",
          items: { type: "string" },
          description: "Application IDs to provision"
        }
      },
      required: ["userIds", "applicationIds"]
    },
  },

• src/tools/onboarding.ts:22-25 (schema)

  Zod schema for input validation of provision_applications parameters, used in the handler.

  provisionApplications: z.object({
    userIds: z.array(z.string().min(1, "User ID is required")),
    applicationIds: z.array(z.string().min(1, "Application ID is required")),
  }),