Paylocity MCP Server

Instructions

Implementation Reference

• src/server.ts:598-716 (handler)

  Registration and implementation of the 'add_employee' tool, which handles onboarding by creating a new employee record via the Paylocity API.

  server.tool(
    "add_employee",
    `Add a new employee to the system (onboarding). Creates the employee record with
  personal info, job details, and compensation. SSN is required by Paylocity but will
  not be stored in conversation — pass it directly and it will be sent encrypted.
  Returns the new employee ID.`,
    {
      companyId: companyIdParam,
      firstName: z.string(),
      lastName: z.string(),
      ssn: z.string().describe("Social Security Number (XXX-XX-XXXX)"),
      birthDate: z.string().describe("YYYY-MM-DD"),
      gender: z.enum(["M", "F"]).optional(),
      hireDate: z.string().describe("YYYY-MM-DD"),
      // Address
      address1: z.string(),
      city: z.string(),
      state: z.string().describe("2-letter state code"),
      zip: z.string(),
      // Contact
      personalEmailAddress: z.string().optional(),
      personalMobilePhone: z.string().optional(),
      workEmailAddress: z.string().optional(),
      // Job
      jobTitle: z.string().optional(),
      costCenter1: z.string().optional().describe("Department/cost center code"),
      employeeType: z
        .string()
        .optional()
        .describe("RFT=Regular Full-Time, RPT=Regular Part-Time, TFT=Temp Full-Time, TPT=Temp Part-Time"),
      supervisorEmployeeId: z.string().optional(),
      // Pay
      payType: z
        .enum(["Salary", "Hourly"])
        .optional()
        .describe("Salary or Hourly"),
      annualSalary: z.number().optional(),
      baseRate: z.number().optional().describe("Hourly rate"),
      payFrequency: z
        .string()
        .optional()
        .describe("S=Semi-monthly, B=Biweekly, W=Weekly, M=Monthly"),
      defaultHours: z.number().optional(),
    },
    async ({
      companyId,
      firstName,
      lastName,
      ssn,
      birthDate,
      gender,
      hireDate,
      address1,
      city,
      state,
      zip,
      personalEmailAddress,
      personalMobilePhone,
      workEmailAddress,
      jobTitle,
      costCenter1,
      employeeType,
      supervisorEmployeeId,
      payType,
      annualSalary,
      baseRate,
      payFrequency,
      defaultHours,
    }) => {
      try {
        const cid = resolveCompanyId(companyId);
  
        const newEmployee: Record<string, any> = {
          companyNumber: cid,
          autoGenerateEmployeeId: true,
          firstName,
          lastName,
          ssn,
          birthDate,
          hireDate,
          employeeStatus: "A",
          address1,
          city,
          state,
          zip,
          country: "USA",
        };
  
        if (gender) newEmployee.sex = gender;
        if (personalEmailAddress)
          newEmployee.personalEmailAddress = personalEmailAddress;
        if (personalMobilePhone)
          newEmployee.personalMobilePhone = personalMobilePhone;
        if (workEmailAddress) newEmployee.workEmailAddress = workEmailAddress;
        if (jobTitle) newEmployee.title = jobTitle;
        if (costCenter1) newEmployee.costCenter1 = costCenter1;
        if (employeeType) newEmployee.employmentType = employeeType;
        if (supervisorEmployeeId)
          newEmployee.supervisorID = supervisorEmployeeId;
        if (payType) {
          newEmployee.rateCode = payType;
          newEmployee.ratePer = payType === "Hourly" ? "Hour" : "Year";
        }
        if (annualSalary) newEmployee.annualSalary = annualSalary;
        if (baseRate) newEmployee.baseRate = baseRate;
        if (payFrequency) newEmployee.payFrequency = payFrequency;
        if (defaultHours) newEmployee.defaultHours = defaultHours;
  
        const result = await client.post(
          `/v2/companies/${cid}/employees`,
          { newEmployee }
        );
  
        // Invalidate directory cache
        directoryCacheTime = 0;
  
        return ok({ success: true, result: redact(result) });
      } catch (e) {
        return err(e);