Okta MCP Server

Instructions

Implementation Reference

• src/tools/users.ts:424-520 (handler)

  The main handler function for the 'list_users' tool. It validates input parameters using Zod schema, constructs query parameters for the Okta API, fetches the list of users, iterates through them using a for-await loop, formats a detailed text response including user details and pagination info, and returns the content in the expected MCP format.

    list_users: async (request: { parameters: unknown }) => {
      const params = userSchemas.listUsers.parse(request.parameters);
  
      try {
        // Build query parameters
        const queryParams: Record<string, any> = {};
        if (params.limit) queryParams.limit = params.limit;
        if (params.after) queryParams.after = params.after;
        if (params.filter) queryParams.filter = params.filter;
        if (params.search) queryParams.search = params.search;
        if (params.sortBy) queryParams.sortBy = params.sortBy;
        if (params.sortOrder) queryParams.sortOrder = params.sortOrder;
  
        const oktaClient = getOktaClient();
  
        // Get users list
        const users = await oktaClient.userApi.listUsers(queryParams);
  
        if (!users) {
          return {
            content: [
              {
                type: "text",
                text: "No users data was returned from Okta.",
              },
            ],
          };
        }
  
        // Format the response
        let formattedResponse = "Users:\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 matching your criteria.",
              },
            ],
          };
        }
  
        // 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: ${count}\n`;
        }
  
        return {
          content: [
            {
              type: "text",
              text: formattedResponse,
            },
          ],
        };
      } catch (error) {
        console.error("Error listing users:", error);
        return {
          content: [
            {
              type: "text",
              text: `Failed to list users: ${error instanceof Error ? error.message : String(error)}`,
            },
          ],
          isError: true,
        };
      }
    },

• src/tools/users.ts:19-26 (schema)

  Zod schema definition for validating the input parameters of the list_users tool, used in the handler for parsing request.parameters.

  listUsers: z.object({
    limit: z.number().min(1).max(200).optional().default(50),
    filter: z.string().optional(),
    search: z.string().optional(),
    after: z.string().optional(),
    sortBy: z.string().optional(),
    sortOrder: z.enum(["asc", "desc"]).optional().default("asc"),
  }),

• src/tools/users.ts:184-218 (registration)

  The tool registration object in the userTools export array, defining the name 'list_users', description, and JSON inputSchema for MCP tool registration.

  {
    name: "list_users",
    description: "List users from Okta with optional filtering and pagination",
    inputSchema: {
      type: "object",
      properties: {
        limit: {
          type: "number",
          description:
            "Maximum number of users to return (default: 50, max: 200)",
        },
        filter: {
          type: "string",
          description: "SCIM filter expression to filter users",
        },
        search: {
          type: "string",
          description: "Free-form text search across multiple fields",
        },
        after: {
          type: "string",
          description: "Cursor for pagination, obtained from previous response",
        },
        sortBy: {
          type: "string",
          description: "Field to sort results by",
        },
        sortOrder: {
          type: "string",
          description: "Sort order (asc or desc, default: asc)",
          enum: ["asc", "desc"],
        },
      },
    },
  },