Okta MCP Server

Instructions

Implementation Reference

• src/tools/users.ts:522-566 (handler)

  Handler function that executes the create_user tool: validates input with Zod schema, creates user via Okta SDK, handles errors, and formats response.

    create_user: async (request: { parameters: unknown }) => {
      const params = userSchemas.createUser.parse(request.parameters);
  
      try {
        const oktaClient = getOktaClient();
  
        const newUser = {
          profile: {
            firstName: params.firstName,
            lastName: params.lastName,
            email: params.email,
            login: params.login || params.email,
          },
        };
  
        const user = await oktaClient.userApi.createUser({
          body: newUser,
          activate: params.activate,
        });
  
        return {
          content: [
            {
              type: "text",
              text: `User created successfully:
  ID: ${user.id}
  Login: ${user.profile?.login}
  Status: ${user.status}
  Created: ${formatDate(user.created)}`,
            },
          ],
        };
      } catch (error) {
        console.error("Error creating user:", error);
        return {
          content: [
            {
              type: "text",
              text: `Failed to create user: ${error instanceof Error ? error.message : String(error)}`,
            },
          ],
          isError: true,
        };
      }
    },

• src/tools/users.ts:28-34 (schema)

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

  createUser: z.object({
    firstName: z.string().min(1, "First name is required"),
    lastName: z.string().min(1, "Last name is required"),
    email: z.string().email("Valid email is required"),
    login: z.string().optional(),
    activate: z.boolean().optional().default(false),
  }),

• src/tools/users.ts:219-249 (registration)

  Tool registration definition including name, description, and JSON inputSchema for the MCP tool system.

  {
    name: "create_user",
    description: "Create a new user in Okta",
    inputSchema: {
      type: "object",
      properties: {
        firstName: {
          type: "string",
          description: "User's first name",
        },
        lastName: {
          type: "string",
          description: "User's last name",
        },
        email: {
          type: "string",
          description: "User's email address",
        },
        login: {
          type: "string",
          description: "User's login (defaults to email if not provided)",
        },
        activate: {
          type: "boolean",
          description:
            "Whether to activate the user immediately (default: false)",
        },
      },
      required: ["firstName", "lastName", "email"],
    },
  },

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

  Utility function to initialize and return the OktaClient instance, used by the create_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/index.ts:6-6 (registration)

  Aggregation of all tool registrations including create_user from userTools.

  export const TOOLS = [...userTools, ...groupTools, ...onboardingTools];