Okta MCP Server

Instructions

Implementation Reference

• src/tools/users.ts:343-422 (handler)

  The core handler function for the 'get_user' MCP tool. Parses input parameters using Zod schema, initializes Okta client, fetches user details via Okta SDK, formats comprehensive user profile (personal info, employment, contact, dates) into a markdown-style text response, and handles errors gracefully.

    get_user: async (request: { parameters: unknown }) => {
      const { userId } = userSchemas.getUser.parse(request.parameters);
  
      try {
        const oktaClient = getOktaClient();
  
        const user = await oktaClient.userApi.getUser({ userId });
  
        if (!user.profile) {
          throw new Error("User profile is undefined");
        }
  
        const formattedUser = `• User Details:
    ID: ${user.id}
    Status: ${user.status}
  
  - Account Dates:
    Created: ${formatDate(user.created)}
    Activated: ${formatDate(user.activated)}
    Last Login: ${formatDate(user.lastLogin)}
    Last Updated: ${formatDate(user.lastUpdated)}
    Status Changed: ${formatDate(user.statusChanged)}
    Password Changed: ${formatDate(user.passwordChanged)}
  
  - Personal Information:
    Login: ${user.profile.login}
    Email: ${user.profile.email}
    Secondary Email: ${getProfileValue(user.profile.secondEmail)}
    First Name: ${user.profile.firstName}
    Last Name: ${user.profile.lastName}
    Display Name: ${user.profile.displayName}
    Nickname: ${getProfileValue(user.profile.nickName)}
  
  - Employment Details:
    Organization: ${user.profile.organization}
    Title: ${user.profile.title}
    Division: ${user.profile.division}
    Department: ${user.profile.department}
    Employee Number: ${user.profile.employeeNumber}
    User Type: ${user.profile.userType}
    Cost Center: ${user.profile.costCenter}
    Manager: ${getProfileValue(user.profile.manager)}
    ManagerId ${getProfileValue(user.profile.managerId)}
  
  - Contact Information:
    Mobile Phone: ${getProfileValue(user.profile.mobilePhone)}
    Primary Phone: ${getProfileValue(user.profile.primaryPhone)}
    
  - Address:
    Street: ${user.profile.streetAddress}
    City: ${user.profile.city}
    State: ${user.profile.state}
    Zip Code: ${user.profile.zipCode}
    Country: ${user.profile.countryCode}
  
  - Preferences:
    Preferred Language: ${user.profile.preferredLanguage}
    Profile URL: ${getProfileValue(user.profile.profileUrl)}`;
  
        return {
          content: [
            {
              type: "text",
              text: formattedUser,
            },
          ],
        };
      } catch (error) {
        console.error("Error fetching user:", error);
        return {
          content: [
            {
              type: "text",
              text: `Failed to get user: ${error instanceof Error ? error.message : String(error)}`,
            },
          ],
          isError: true,
        };
      }
    },

• src/tools/users.ts:135-148 (registration)

  MCP tool registration entry for 'get_user' within the userTools array export. Defines the tool name, description, and JSON input schema for Model Context Protocol integration.

  {
    name: "get_user",
    description: "Retrieve detailed user information from Okta by user ID",
    inputSchema: {
      type: "object",
      properties: {
        userId: {
          type: "string",
          description: "The unique identifier of the Okta user",
        },
      },
      required: ["userId"],
    },
  },

• src/tools/users.ts:7-9 (schema)

  Zod runtime validation schema for 'get_user' tool input parameters, ensuring userId is a non-empty string. Used in the handler for safe parsing.

  getUser: z.object({
    userId: z.string().min(1, "User ID is required"),
  }),

• src/tools/users.ts:63-83 (helper)

  Utility helper function to instantiate the Okta SDK client using environment variables OKTA_ORG_URL and OKTA_API_TOKEN. Called by the get_user handler and other user tools.

  function getOktaClient() {
    const oktaDomain = process.env.OKTA_ORG_URL;
    const apiToken = process.env.OKTA_API_TOKEN;
  
    if (!oktaDomain) {
      throw new Error(
        "OKTA_ORG_URL environment variable is not set. Please set it to your Okta domain."
      );
    }
  
    if (!apiToken) {
      throw new Error(
        "OKTA_API_TOKEN environment variable is not set. Please generate an API token in the Okta Admin Console."
      );
    }
  
    return new OktaClient({
      orgUrl: oktaDomain,
      token: apiToken,
    });
  }

• src/tools/users.ts:91-99 (helper)

  Helper function to safely format dates from Okta user data into readable locale strings, with fallback handling for invalid dates. Extensively used in the get_user response formatting.

  function formatDate(dateString: Date | string | undefined | null): string {
    if (!dateString) return "N/A";
    try {
      return new Date(dateString).toLocaleString();
    } catch (e) {
      return dateString instanceof Date
        ? dateString.toISOString()
        : dateString || "N/A";
    }