# Paylocity MCP connector

The Paylocity connector brings employees, jobs, earnings, deductions, cost centers and documents into Claude, ChatGPT, Cursor and the Elaichi Agent, so each person can look up and update payroll and HR records within their own Paylocity access.

Source: https://elaichi.ai/connectors/paylocity/

## Facts

| | |
| --- | --- |
| Application | Paylocity |
| Category | HRIS |
| AI tools | 51 |
| Authentication | Connects with an API key |
| Bring your own OAuth app | No |
| MCP endpoint | https://api.elaichi.ai/mcp |
| Works with | Claude, ChatGPT, Cursor, any MCP client, and the Elaichi Agent |
| Tools advertised by name | No. Connected tools are never listed one by one, however few there are. The endpoint advertises `search_tools` and `execute_tool` instead |

## What you can ask once Paylocity is connected

- List everyone in the Chicago work location with their positions
- Add a $500 bonus earning for Maria Chen this pay period
- Which jobs are still open in the Engineering cost center?

## Connect Paylocity in Elaichi

This happens once for the organization, before any client is involved.

1. Open Connections, choose Add connection, and pick Paylocity.
2. Optionally set Share with, then press Connect.
3. Paste a Paylocity API key. One person generates a token in Paylocity and pastes it once. Everyone else works through Share with, and never sees it.

Credentials are vaulted and nobody, including the AI, reads them back. The connection becomes a toolbox immediately, so you can curate which Paylocity tools are exposed, rename them, or freeze arguments before anyone points a client at it.

## Paylocity MCP connector for Claude

Endpoint: https://api.elaichi.ai/mcp

1. Open Customize, then Connectors.
2. Press Add.
3. Name it, paste the MCP server URL, then Continue.
4. Sign in and approve.

On Team and Enterprise, an Owner adds it once. Everyone else turns it on for themselves.

## Paylocity MCP connector for ChatGPT

Endpoint: https://api.elaichi.ai/mcp

1. Open Plugins, then press the + button.
2. Name it and paste the endpoint into Server URL.
3. Leave Authentication on OAuth, then tick the risk acknowledgement.
4. Press Create, then sign in and approve.

Works on the web today. The plugin directory lives at chatgpt.com/plugins.

## Paylocity MCP connector for Cursor

Endpoint: https://api.elaichi.ai/mcp

1. Open `~/.cursor/mcp.json`.
2. Add the endpoint under `mcpServers`.
3. Reload Cursor, then sign in and approve.

Set up per machine, so repeat it on each computer you work from.

## Connect Paylocity to any MCP client

Endpoint: https://api.elaichi.ai/mcp

1. Add the endpoint as a remote MCP server.
2. Sign in and approve.

The Elaichi Agent already has these tools, with nothing to set up.

## What the consent screen decides

Only Read is granted by default, which is not enough to call a Paylocity tool. Over MCP there is no trusted place to confirm a write in the moment, so the consent screen is the standing approval rather than a formality. Grant Read and Run tools. Think hard before granting Delete, which reaches into connected apps and cannot be undone.

## What teams do with Paylocity through Elaichi

### Brief yourself on an employee before a meeting

HR. Ask for an employee's position, work location, cost center and pay frequency in Paylocity and have it in front of you before the conversation starts.

### Add a bonus to an employee's earnings

Payroll. Create or update an employee earning in Paylocity from a plain request, then read it back to confirm it before the pay run closes.

### Reconcile headcount by cost center

Finance. List employees, cost centers and positions in Paylocity and get a headcount breakdown ready for the monthly close, without exporting a spreadsheet.

### Open the job as soon as it's approved

Recruiting. Create the job in Paylocity, update its details as the role changes, and remove it once the hire is made.

### Check work locations and positions across sites

Operations. See every Paylocity work location and the positions tied to each, so office moves and reorganizations start from current records.

### Answer a compensation question without a spreadsheet

Leadership. Ask which earnings, deductions and taxes are configured in Paylocity and get a plain answer instead of waiting on an export.

## Frequently asked questions

### How do I connect Paylocity to Claude?

Connect Paylocity in Elaichi first: you paste in your Paylocity API key and the connection is ready, with no OAuth application to register and no client ID or secret to generate. Then open Claude, go to Customize, then Connectors, then Add, and paste https://api.elaichi.ai/mcp. Sign in as yourself and Paylocity employees, jobs and earnings are available in the conversation.

### Does Paylocity work with ChatGPT and Cursor as well as Claude?

Yes. The same endpoint, https://api.elaichi.ai/mcp, works in Claude, ChatGPT, Cursor, any other MCP client and the Elaichi Agent. You connect Paylocity once in Elaichi and every client picks it up.

### What can an AI agent actually do with my Paylocity data?

It can look up employees, positions, work locations, cost centers, pay frequencies, deductions, taxes and company or employee documents in Paylocity, and answer questions about them in plain language. It can also create, update and delete jobs and employee earnings, such as adding a bonus or opening a new role. Short, concrete asks like "list employees in the Denver location" work better than long paragraphs.

### Does connecting Paylocity give the AI access to every employee record?

No. Every call runs as the person who signed in, so the AI only sees the Paylocity employees, earnings and documents that person can already reach. Elaichi can narrow that access further with roles and restrictions, and it can never widen it beyond what Paylocity itself allows.

### Can my team share one Paylocity connection?

Yes. One person connects Paylocity with the API key and shares the connection with a team, and nobody else ever handles the credential. Each teammate still signs in to Elaichi as themselves, so the audit log names the actual person behind every employee lookup or earning change.

### Can I stop an agent from deleting or changing things in Paylocity?

Yes. Restrictions in Elaichi work per action, so you can allow reading Paylocity employees and earnings while blocking creating, updating or deleting jobs and earnings. A restricted action is never advertised to Claude, ChatGPT or Cursor at all, so no prompt can reach it.

### What happens to a Paylocity connection when someone leaves?

Offboarding a person in Elaichi ends their access to Paylocity through every client at once. A shared Paylocity connection keeps working for everyone else on the team. If you want it gone entirely, disconnecting Paylocity once in Elaichi removes it from Claude, ChatGPT, Cursor and the Elaichi Agent together.

### Does the Paylocity MCP connector work with Gemini, Codex, Claude Code or other MCP clients?

Yes. Paylocity is reached over the same MCP endpoint every client uses, so anything that speaks MCP can call it — Gemini, Codex, Claude Code, Windsurf, Cline, Zed and OpenCode among them — alongside Claude, ChatGPT, Cursor, and the Elaichi Agent. The tools on offer and the access behind them are identical whichever client asks. Only the setup screen differs.

## All 51 Paylocity tools

Every tool below is callable through https://api.elaichi.ai/mcp once Paylocity is connected, subject to the toolbox it is in and the restrictions on the caller.

- **List all Paylocity company info** (List). Get the Paylocity company record for the connected company (companyId, companyName, dba, ein, status, entityType, industryType, address, relationships).
Returns one record; not paginated. The credential needs the Company Level Information API.
- **Get single Paylocity company info by ID** (Get). Get the company information (legal name, DBA, EIN, address, status) for one Paylocity Company ID.
- **List all Paylocity employees** (List). List employees (Employee Demographic API v1). Each page comes back as one record: totalCount plus an employees array of up to 20 employees (id, displayName, status, statusType, info, position, currentPayRate, futurePayRates).
Truto sends the include default and follows Paylocity's nextToken cursor. Paylocity does not document where nextToken is returned, so paging past 20 is unverified.
- **Get single Paylocity employee by ID** (Get). Get one employee by Paylocity employee ID (Employee Demographic API v1): id, displayName, status, currentStatus, info, position, currentPayRate, futurePayRates.
Paylocity marks include as required, so Truto sends info,position,status,payrate,futurePayrates unless you pass include.
- **List all Paylocity custom fields** (List). List custom field definitions for a category (category, label, type, isRequired, defaultValue, values). This is a WebLink API path called on the NextGen gateway with the NextGen token: it needs WebLink access and is unverified in production.
Required: category (Paylocity documents only PayrollAndHR). Not paginated. Paylocity says not to use it for companies on Unlimited Custom Fields.
- **List all Paylocity work locations** (List). List the company's work locations (workLocationId, name, address1, address2, city, state, zip, county, countryCode, defaultCurrencyCode).
Returns the full list in one call; not paginated.
- **List all Paylocity positions** (List). List position codes (code, title, effectiveDate, fte, flsaOvertimeExempt, supervisorPosition, eeoClass, workersCompensationCode, careerLevel, families).
Paginated with limit/offset, up to 100 per page.
- **List all Paylocity deductions** (List). List the company's deduction codes (code, description, type, calculationCode, rate, amount, frequency, priority, isActive, wasUsedInPayroll).
Paginated with limit/offset, up to 100 per page.
- **List all Paylocity earnings** (List). List the company's earning codes (code, description, type, calculationCode, rate, amount, frequency, rateCode, isActive, wasUsedInPayroll).
Paginated with limit/offset, up to 100 per page.
- **List all Paylocity pay frequencies** (List). List the company's pay frequency codes (code, description, baseFrequency, blockWeek1 to blockWeek5, blockLastWeek, allowMakeup). They decide when an earning, deduction or agency code is applied.
Returns the full list in one call; not paginated.
- **List all Paylocity taxes** (List). List the company's tax codes (code, description, type, ein, startDate, endDate, depositFrequency, isEmployeeTax, isActive, customFields, rules).
Paginated with limit/offset, up to 100 per page.
- **List all Paylocity cost centers** (List). List Time and Labor cost centers, also called labor levels (id, costCenterId, level, code, name). Only companies on the Time and Labor module have them; payroll cost centers are in payroll-cost-centers.
Paginated with limit/offset, up to 1000 per page.
- **List all Paylocity jobs** (List). List job codes (code, description, isActive, isCertified, payEntry, address, payrollBasedJournal).
Optional filter on code, isActive, isCertified or payrollBasedJournal fields. Paginated with limit/offset, up to 100 per page.
- **Get single Paylocity job by ID** (Get). Get one job code; id is the job code. Returns code, description, isActive, isCertified, payEntry, address, payrollBasedJournal.
- **Create a Paylocity job** (Create). Create a job code. Body: code (required; up to 20 letters or digits, no spaces or special characters), description, isActive, isCertified, payEntry, address, payrollBasedJournal. Job codes must exist before payroll runs.
Returns no content (Paylocity replies 200 with an empty body).
- **Update a Paylocity job by ID** (Update). Replace a job code; id is the job code. This is a full replacement (PUT): Paylocity sets every field you leave out to null or its system default, so send the complete job (read it with jobs.get, change it, send it all).
The code itself comes from id and cannot change. Returns no content.
- **Delete a Paylocity job by ID** (Delete). Delete a job code; id is the job code. Paylocity recommends deactivating a code that was used in payroll (jobs.update) instead of deleting it, because deleting it can affect reports.
Returns no content.
- **List all Paylocity company documents** (List). List company documents (documentId, displayName, receivedDate, uploadedDate, companyId). Metadata only; get the file with document-downloads.create.
Filter by uploadedDate, uploadedDate.greaterThanOrEqualTo or uploadedDate.lessThanOrEqualTo. Paginated with limit/offset, 100 per page (Paylocity documents no maximum).
- **List all Paylocity employee documents** (List). List employee documents (documentId, employeeId, displayName, category, receivedDate, uploadedDate, companyConfidential, employeeConfidential). Metadata only; get the file with document-downloads.create.
Filter by employeeId and uploadedDate (equals, greaterThanOrEqualTo, lessThanOrEqualTo). Paginated with limit/offset, 100 per page (Paylocity documents no maximum).
- **List all Paylocity employee earnings** (List). List an employee's active recurring earnings (id, code, frequency, recordType, rate, amount, units, calculationCode, rateCode, effectiveDate, beginCheckDate, endCheckDate, distribution). id is the record's resourceId for get, update and delete.
Required: employee_id. Optional filter. Paginated with limit/offset, up to 250 per page.
- **Get single Paylocity employee earning by ID** (Get). Get one recurring earning record; id is its resourceId (the id from employee-earnings.list). Returns code, frequency, recordType, rate, amount, units, calculationCode, effectiveDate, distribution, limits.
Required: employee_id, earning_code, id.
- **Create a Paylocity employee earning** (Create). Add a recurring earning to an employee (code, effectiveFrom, effectiveTo, calculationCode, rate, units, amount, frequency, rateCode, agency, distribution, limits). Returns the created record with its id.
Required: employee_id. The spec marks no body field as required; its examples always send code, effectiveFrom, calculationCode and frequency.
- **Update a Paylocity employee earning by ID** (Update). Update one recurring earning record; id is its resourceId. The body takes the create fields except code (rate, units, amount, frequency, effectiveFrom, effectiveTo, distribution, limits and others); the spec examples send only the fields being changed.
Required: employee_id, earning_code, id. Returns no content.
- **Delete a Paylocity employee earning by ID** (Delete). Delete one recurring earning record; id is its resourceId (the id from employee-earnings.list).
Required: employee_id, earning_code, id. Returns no content.
- **List all Paylocity employee shifts** (List). List an employee's scheduled shifts (stackId, startDateTime, duration, positionKey, costCenters, shiftId, scheduleId, isPublished). breaks, segments and note are added with include.
Required: employee_id. Optional filter on startDateTime or positionKey, and sort. Paginated with limit/offset, 100 per page.
- **List all Paylocity employees v 2** (List). List employees with Employee Demographic API v2, an early-access beta Paylocity says not to rely on in production. Records have the sections contact, sensitive, workAuthorization, rates, employmentInformation, assignments, position, workLocation, status and timeLabor.
Pick sections with fields; narrow with filter. Paginated with limit/offset, up to 20 per page.
- **Get single Paylocity employees v 2 by ID** (Get). Get one employee with Employee Demographic API v2 (early-access beta). Sections: contact, sensitive, workAuthorization, rates, employmentInformation, assignments, position, workLocation, status, timeLabor.
id is the Paylocity employee ID; pick sections with fields.
- **List all Paylocity rate codes** (List). List the company's rate codes (code, description).
Returns the full list in one call; not paginated.
- **List all Paylocity payroll cost centers** (List). List payroll cost centers grouped by level: each record is a level (id, level, description) with a costCenters array (id, code, name, isActive).
Returns the full list in one call; not paginated. Time and Labor cost centers are in cost-centers.
- **Update a Paylocity payroll cost center by ID** (Update). Create or replace (upsert) a payroll cost center in a level. id is the cost center code, which is permanent once used; level is the level number. Body: name (required) and isActive.
Returns no content (201 when created, 204 when replaced). Cost centers cannot be deleted; remove employees from one before deactivating it.
- **List all Paylocity pay grades** (List). List pay grades (code, description, minimum, midpoint, maximum, active, payGradeKey, payGradeCompanies).
Paginated with limit/offset, up to 100 per page.
- **List all Paylocity worker compensation codes** (List). List workers' compensation codes (code, description, active, positionsAssigned, clientId).
Paginated with limit/offset, up to 100 per page.
- **List all Paylocity employee deductions** (List). List an employee's active recurring deductions (id, code, type, rate, frequency, calculationCode, priority, recordType, effectiveDate, beginCheckDate, endCheckDate, limits). id is the record's resourceId for get, update and delete.
Required: employee_id. Optional filter. Paginated with limit/offset, up to 250 per page.
- **Get single Paylocity employee deduction by ID** (Get). Get one recurring deduction record; id is its resourceId (the id from employee-deductions.list). Returns code, type, rate, frequency, calculationCode, priority, recordType, effectiveDate, limits, loan401K.
Required: employee_id, deduction_code, id.
- **Create a Paylocity employee deduction** (Create). Add a recurring deduction to an employee (code, effectiveFrom, effectiveTo, calculationCode, rate, frequency, priority, note, agency, arrear, loan401K, costCenters, limits). Garnishments cannot be created here. Returns the created record with its id.
Required: employee_id. The spec marks no body field as required; its examples always send code, effectiveFrom, rate, frequency, note and priority.
- **Update a Paylocity employee deduction by ID** (Update). Update one recurring deduction record; id is its resourceId. The body takes the create fields except code (rate, frequency, effectiveFrom, effectiveTo, note, priority, limits and others); the spec examples send only the fields being changed. Garnishments cannot be updated here.
Required: employee_id, deduction_code, id. Returns no content.
- **Delete a Paylocity employee deduction by ID** (Delete). Delete one recurring deduction record; id is its resourceId (the id from employee-deductions.list).
Required: employee_id, deduction_code, id. Returns no content.
- **List all Paylocity employee earnings by code** (List). List all of an employee's records for one earning code (id, code, frequency, recordType, rate, amount, units, effectiveDate, beginCheckDate, endCheckDate).
Required: employee_id, earning_code. Returns the full list in one call; not paginated.
- **List all Paylocity employee deductions by code** (List). List all of an employee's records for one deduction code (id, code, type, rate, frequency, recordType, effectiveDate, beginCheckDate, endCheckDate).
Required: employee_id, deduction_code. Returns the full list in one call; not paginated.
- **List all Paylocity employee bank accounts** (List). List an employee's direct deposit bank accounts (bankAccountId, bankName, accountNumber, routingNumber). Sensitive data.
Required: employee_id. Returns the full list in one call; not paginated.
- **Get single Paylocity employee bank account by ID** (Get). Get one direct deposit bank account; id is its bankAccountId. Returns bankAccountId, bankName, accountNumber, routingNumber. Sensitive data.
Required: employee_id, id.
- **List all Paylocity company shifts** (List). List scheduled shifts across the company (stackId, assignedTo, startDateTime, duration, positionKey, costCenters, shiftId, scheduleId, isPublished, isDeleted). breaks, draft, segments and note are added with include.
Optional filter on startDateTime or positionKey, and sort. Paginated with limit/offset, 100 per page.
- **List all Paylocity open shifts** (List). List open (unassigned) shifts (stackId, quantity, startDateTime, duration, positionKey, costCenters, scheduleId, isPublished). breaks, note and claims are added with include.
Optional filter on startDateTime or positionKey, and sort. Paginated with limit/offset, 100 per page.
- **Create a Paylocity document download** (Create). Create a temporary download URL for a company or employee document (documentId, downloadUrl, expiresIn).
Required: document_id (from company-documents.list or employee-documents.list). No request body.
- **Create a Paylocity punch detail** (Create). Start a company punch detail operation for a time window (step 1 of 3). Body: relativeStart and relativeEnd, without time zone. Returns 202 Accepted with no response body; the Location response header holds the operation URL, whose last segment is the id for punch-detail-operations.get.
Only one operation per company runs at a time (409 otherwise). Proxy API callers receive the header; MCP tool results do not include headers.
- **List all Paylocity punch details** (List). Get the punch data of a finished punch detail operation (step 3 of 3): one record per worked shift (employeeId, badgeNumber, relativeStart, relativeEnd, segments with punchType, durationHours, earnings, costCenters).
Required: resource_id. Optional sort on relativeStart or relativeEnd. Paginated with limit/offset, up to 100 per page.
- **Get single Paylocity punch detail operation by ID** (Get). Get a punch detail operation's status (step 2 of 3): status (pending, running, succeeded, failed), created, lastUpdated, location, warnings, errors. id is the operation id.
When status is succeeded, the last path segment of location is the resource_id for punch-details.list.
- **List all Paylocity employee punch details** (List). List one employee's punches for a time window (Punch Detail v2): one record per worked shift (employeeId, badgeNumber, relativeStart, relativeEnd, segments). Hours use four-decimal precision.
Required: employee_id, relativeStart, relativeEnd (date-times without time zone, such as 2024-03-05T00:00:00). Returns the full list in one call; not paginated.
- **Create a Paylocity pay entry batch** (Create). Submit a payroll batch for a check date to Run Payroll (batchName, checkDate, payPeriodBeginDate, payPeriodEndDate, checkType, autoAcknowledge, mergeBatchId, payEntries). Returns 202 with fileName, timeImportFileTrackingId and status.
Poll pay-entry-batches.get with timeImportFileTrackingId as the id.
- **Get single Paylocity pay entry batch by ID** (Get). Get the status of a submitted payroll batch; id is the timeImportFileTrackingId from pay-entry-batches.create. Returns fileName, timeImportFileTrackingId and status.
Paylocity's text says the status response also reports creation time, a summary and validation errors, but the spec documents only these three fields.
- ...and 1 more tools. Call `tools/list` via the MCP endpoint, or see the full catalog via the API, for the complete set.