Okta MCP Server

Instructions

Implementation Reference

• src/tools/groups.ts:340-383 (handler)

  The primary handler function for the 'create_group' tool. It validates input using Zod schema, constructs the group profile, calls the Okta API to create the group, formats the response, and handles errors.

    create_group: async (request: { parameters: unknown }) => {
      const { name, description } = groupSchemas.createGroup.parse(
        request.parameters
      );
  
      try {
        const oktaClient = getOktaClient();
  
        const newGroup = {
          profile: {
            name,
            description: description || "",
          },
        };
  
        const group = await oktaClient.groupApi.createGroup({
          group: newGroup,
        });
  
        return {
          content: [
            {
              type: "text",
              text: `Group created successfully:
  ID: ${group.id}
  Name: ${group.profile?.name}
  Type: ${group.type || "OKTA_GROUP"}
  Created: ${formatDate(group.created)}`,
            },
          ],
        };
      } catch (error) {
        console.error("Error creating group:", error);
        return {
          content: [
            {
              type: "text",
              text: `Failed to create group: ${error instanceof Error ? error.message : String(error)}`,
            },
          ],
          isError: true,
        };
      }
    },

• src/tools/groups.ts:16-19 (schema)

  Zod schema definition for validating the input parameters (name and optional description) of the create_group tool.

  createGroup: z.object({
    name: z.string().min(1, "Group name is required"),
    description: z.string().optional(),
  }),

• src/tools/groups.ts:130-147 (registration)

  Tool registration entry in the groupTools array, which defines the tool's name, description, and JSON input schema for MCP protocol compliance. This array is exported and combined in src/tools/index.ts.

  {
    name: "create_group",
    description: "Create a new group in Okta",
    inputSchema: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "Name of the group",
        },
        description: {
          type: "string",
          description: "Description of the group (optional)",
        },
      },
      required: ["name"],
    },
  },

• src/tools/index.ts:6-6 (registration)

  Central registration where groupTools (including create_group) is spread into the main TOOLS export for the MCP server.

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

• src/tools/groups.ts:47-67 (helper)

  Utility function to initialize and return the OktaClient instance, used by the create_group handler to interact with the Okta API.

  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,
    });
  }