# UKG Dimensions MCP connector

The UKG Dimensions connector brings employee records, supervisors, cost centers, pay periods, locations, and jobs to Claude, ChatGPT, Cursor, and the Elaichi Agent, so each person asks questions and updates records inside their own UKG Dimensions access.

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

## Facts

| | |
| --- | --- |
| Application | UKG Dimensions |
| Category | HRIS |
| AI tools | 75 |
| 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 UKG Dimensions is connected

- Who reports to Dana Ruiz at the Denver distribution center?
- List everyone in cost center 4120 with their job titles
- Update Priya Shah's supervisor to Marcus Lee

## Connect UKG Dimensions in Elaichi

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

1. Open Connections, choose Add connection, and pick UKG Dimensions.
2. Optionally set Share with, then press Connect.
3. Paste an UKG Dimensions API key. One person generates a token in UKG Dimensions 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 UKG Dimensions tools are exposed, rename them, or freeze arguments before anyone points a client at it.

## UKG Dimensions 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.

## UKG Dimensions 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.

## UKG Dimensions 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 UKG Dimensions 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 UKG Dimensions 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 UKG Dimensions through Elaichi

### Catch an employee record up after a change

HR. When someone moves teams or gets a new manager, ask for their UKG Dimensions record and update the supervisor, job, or location in the same conversation instead of clicking through menus.

### Check who falls in this pay period

Payroll. Pull the current pay periods and employee groups from UKG Dimensions to confirm who is covered before payroll closes, and spot anyone missing employment terms.

### See who reports to a manager at a location

Operations. Ask for the people and supervisors at a given UKG Dimensions location and get a plain list back, ready to paste into a shift plan or a handover note.

### Reconcile headcount by cost center

Finance. Search UKG Dimensions cost centers and list the people assigned to each, so the budget lines match the org chart before the month closes.

### Onboard a batch of new hires at once

HR. Paste a list of new starters and create their UKG Dimensions person records in one go, with jobs, locations, and external IDs filled in from the list.

### Find the right job and location codes

Store management. Ask which jobs and location sets exist in UKG Dimensions before assigning someone, instead of guessing a code and fixing it later.

## Frequently asked questions

### How do I connect UKG Dimensions to Claude?

Connect UKG Dimensions in Elaichi first, which asks for your UKG Dimensions API key and nothing else. There is no OAuth application to register and no client ID or secret to generate. Then in Claude open Customize, then Connectors, then Add, and paste https://api.elaichi.ai/mcp. Sign in as yourself and UKG Dimensions is ready to use in Claude.

### Does UKG Dimensions work with ChatGPT and Cursor as well as Claude?

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

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

It can look up an employee in UKG Dimensions along with their supervisor, employment terms, and external IDs, list the people at a location or in a cost center, and find jobs, employee groups, pay periods, and location sets. It can also create and update person records, including many at once from a list, and remove a record if you allow that. Short, concrete asks such as "who reports to Dana at the Denver center" work better than long paragraphs.

### Does connecting UKG Dimensions give the AI access to every employee?

No. Every request runs as the person who signed in, so if you can only see your own locations in UKG Dimensions, the agent sees only those too. Elaichi can narrow that access further, for example to lookups only, but it can never widen what UKG Dimensions already lets you do.

### Can my team share one UKG Dimensions connection?

Yes. One person connects UKG Dimensions with the API key and shares the connection with a team in Elaichi, and nobody else ever handles the key. Each teammate still signs in as themselves, so every lookup or change to a UKG Dimensions person record is logged under their own name.

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

Yes. Restrictions in Elaichi work per action, so you can allow reading UKG Dimensions people, cost centers, and pay periods while blocking updates, bulk changes, or deleting a person record. A restricted action is never advertised to Claude, ChatGPT, or Cursor, so no prompt can reach it.

### What happens to a UKG Dimensions connection when someone leaves?

Offboarding a person in Elaichi ends their access to UKG Dimensions through every client at once. A connection they shared keeps working for everyone else on the team, and the audit log keeps their history. If you need to remove UKG Dimensions entirely, disconnecting it once in Elaichi removes it from Claude, ChatGPT, Cursor, and every other client.

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

Yes. UKG Dimensions 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 75 UKG Dimensions tools

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

- **List all UKG Dimensions current user info** (List). Get the person this connection signs in as (the API user). Returns one record with employeeId, personNumber, userName, firstName, lastName, middleInitial, timeZone and userLocale.
Set include_contact_information=true to add emailContacts, telephoneContacts and postalAddresses. Truto uses this call to validate the connection. Access Control Point: CURRENT_USER_INFORMATION_READ.
- **List all UKG Dimensions persons** (List). List every person as a lightweight record: personId, personNumber, firstName, lastName, employmentStatus and userAccountStatus.
Optional filters go in the body where object (employmentStatus, userAccountStatus, snapshotDate, dateRange, returnPersonIdOnly); the default where: {} returns everyone.
Truto pages this for you: pass limit and next_cursor, not index or count. Pages hold up to 1,000 people (UKG allows at most 10,000 per call). For full records use persons.get, or person_extensions.list for up to 100 people at a time.
Access Control Point: LIGHT_WEIGHT_EMPLOYEE_RECORDS_READ.
- **Get single UKG Dimensions person by ID** (Get). Get one person's full record by person ID (UKG's internal person key, also called the employee ID; not the person number).
Returns personIdentity, personInformation (names, email addresses, phone numbers, postal addresses, employment and user account status history, custom data), jobAssignment (primary labor accounts, job assignment details, base wage rates), user (userAccount), gdapAssignments and positions.
- **Update a UKG Dimensions person by ID** (Update). Update a person by person ID (PUT /v1/commons/persons/{id}). Send the person record: personInformation is required, plus any of personIdentity, jobAssignment, user, gdapAssignments and positions. Returns the updated record. UKG returns 409 on an optimistic-locking conflict.
- **Create a UKG Dimensions person** (Create). Create a person (employee and/or user). Send the person record: personInformation is required, plus any of personIdentity, jobAssignment, user, gdapAssignments and positions. Returns the created record. UKG answers 200 (not 201) for a successful create.
- **UKG Dimensions persons bulk upsert** (Upsert). Create or update several people in one call: the body is a JSON array of person records, each with personInformation. The maximum batch size is 100; UKG notes batches of about 70 often perform better. Returns an array of the saved records. A 207 response means partial success and lists the records that failed.
- **Delete a UKG Dimensions person by ID** (Delete). Permanently delete a person record by ID (the UKG person ID, which UKG also calls employee ID; not a person number). This is a hard delete of the person and of the timekeeping, punch, accrual, schedule and request data that belongs to them; UKG documents no archive and no cascade behaviour, and answers 204 with no body. UKG allows it for inactive and terminated employees outside of the current pay period (release note WFD-154391) and rejects other people with 400. The reversible way to offboard in UKG is an effective-dated Terminated employment status.
- **List all UKG Dimensions person extensions** (List). Get full person records for specific people, grouped into extensions (employeeExtension, timekeepingExtension, schedulingExtension, accrualExtension, deviceExtension, or allExtension).
Identify people in where.employees with key (personid, personnumber, jobassignmentid, username, useraccountid, badgenumber or useremailaddress) and values, and pick the extension with where.extensionType.
At most 100 employees per request (People multi_* service limit). Not paginated.
- **List all UKG Dimensions base persons** (List). Get the base summary (personId, personNumber, fullName, displayName, name) for specific people. Identify them in where.employees with key (personid, personnumber, jobassignmentid, username, useraccountid, badgenumber or useremailaddress) and values. At most 100 employees per request (People multi_* service limit). Not paginated.
- **List all UKG Dimensions person external IDS** (List). Get the AOID and COID external identifiers (UKG Pro HCM / ADP IDs) of specific employees. Identify them in where.employees with key (personid, personnumber, jobassignmentid, username, useraccountid, badgenumber or useremailaddress) and values. Returns personIdentity, aoid and coid per employee. Not paginated.
- **List all UKG Dimensions person supervisors** (List). Get the supervisor ('reports to') assignments of specific employees. Identify them in where.employees with key and values. Returns personidentity, supervisorName and supervisorPersonNumber per employee. At most 100 records per request. Not paginated. Access Control Point: PE_REPORTS_TO_FIELD.
- **List all UKG Dimensions person employment terms** (List). Get the employment term assignments of specific employees. Identify them in where.employees with key and values. Returns personIdentity, assignmentSpan and assignments per employee. Not paginated.
- **List all UKG Dimensions cost centers** (List). List every cost center (id, name, description, inactive, ivrNum, persistentId, version) in one response. Not paginated. Access Control Point: COST_CENTERS.
- **UKG Dimensions cost centers search** (Search). Search cost centers with filters and sorting: where.filterCriteria (name, description, ivrNum, inactive, supportPartialStringMatch) and sortBy. Not auto-paginated: send index (0-based page number) and count in the body and request the next index until fewer than count records come back. UKG documents no upper limit for count.
- **Get single UKG Dimensions cost center by ID** (Get). Retrieve one cost center (id, name, description, inactive flag) by its ID. Access Control Point COST_CENTERS.
- **List all UKG Dimensions employee groups** (List). List employee groups (id and name only, unless all_details=true). Pass qualifier to get one group by name. Truto pages this for you: pass limit and next_cursor, not index or count. Pages hold up to 100 groups (the UKG default page size). Access Control Point: EMPLOYEE_GROUP.
- **List all UKG Dimensions symbolic periods** (List). List every symbolic period (id and qualifier), such as Current_Payperiod or Previous_Payperiod. Use them as symbolic period references in timecard, schedule and data requests. Not paginated.
- **List all UKG Dimensions pay periods** (List). Get one pay period timespan. With no parameters it returns the current pay period of the API user. Otherwise pass pay_period_id, pay_rule_id or employee_id (optionally with date), plus period_type (Previous, Current or Next). Returns one record with spanStartDate, spanEndDate, spanStartDateTime and spanEndDateTime.
- **List all UKG Dimensions locations** (List). List the organizational map locations below a location during a date span (POST /v2/commons/locations/multi_read).
Send where.descendantsOfDuring with context (ORG or FORECAST), locationRef, startDate and endDate, plus optional multiReadOptions (includeOrgPathDetails, excludeExpiredNodes, modifiedSince).
Truto pages this for you: pass limit and next_cursor, not index or count. Pages hold up to 100 locations.
- **Get single UKG Dimensions location by ID** (Get). Get one organizational map location (node) by nodeId. The context (ORG or FORECAST) and date query parameters are required.
- **UKG Dimensions locations search** (Search). Find organizational map locations (POST /v1/commons/locations/multi_read).
Put one criterion in where: descendantsOf, childrenOf, ancestorsOf, parentOf (or their ...During forms), locationSet, locationsSpan or query (search by name). multiReadOptions can add includeOrgPathDetails, modifiedSince or excludeExpiredNodes.
Returns every match in one response; not paginated.
- **List all UKG Dimensions jobs** (List). Get generic jobs by date or reference (POST /v1/commons/jobs/multi_read).
Put one criterion in where: forDate (all jobs effective on a date), allJobsBySpan (a date span) or span (specific job references). multiReadOptions.modifiedSince returns only jobs changed since then.
At most 5,000 jobs per request (Business Structure service limit). Not paginated.
- **Get single UKG Dimensions job by ID** (Get). Get one effective generic job by job ID. The date query parameter (YYYY-MM-DD) is required.
- **List all UKG Dimensions location sets** (List). List location sets (organizational map groups). Filter with qualifier, date and context (ORG or FORECAST); all_details=true returns full records. Truto pages this for you: pass limit and next_cursor, not index or count. Pages hold up to 100 location sets (the UKG default).
- **UKG Dimensions location sets search** (Search). Find location sets by identifier or by a name query (POST /v2/commons/location_sets/multi_read).
Send where with context, date, and either locationSets or query; types accepts ids 1 (all organizational groups), 2 (manager groups) or 3 (transfer groups).
Not auto-paginated: send index (0-based page number) and count in the body and request the next index until fewer than count records come back. Access Control Point: OJS_EDITOR (VIEW).
- **List all UKG Dimensions labor categories** (List). List labor categories. Pass name to get one category, or modified_since (an ISO local date-time such as 2026-01-31T00:00:00.000) to get only categories changed since then. Not paginated. Access Control Point: LABOR_CATEGORY.
- **Get single UKG Dimensions labor category by ID** (Get). Retrieve one labor category (id, name, abbreviation, sort order, inactive flag) by its ID. Access Control Point LABOR_CATEGORY.
- **List all UKG Dimensions labor entries** (List). List every labor category entry of one labor category. The categoryId query parameter is required. Not paginated. Access Control Point: LABOR_CATEGORY.
- **UKG Dimensions labor entries search** (Search). Search labor category entries with filters and sorting: where.laborCategory, where.filterCriteria (name, description, ivrNum, inactive, supportPartialStringMatch) and sortBy. Not auto-paginated: send index (0-based page number) and count in the body and request the next index until fewer than count records come back.
- **Get single UKG Dimensions labor entry by ID** (Get). Retrieve one labor category entry (id, name, description, inactive flag, labor category) by its ID. Access Control Point LABOR_CATEGORY.
- **List all UKG Dimensions hyperfinds** (List). List the Hyperfind queries (saved people searches) visible to the API user. usage_type filters to Regular, Home or All; all_details=true adds constraints. Use a Hyperfind id to scope timecard, schedule and data requests. Not paginated.
- **Get single UKG Dimensions hyperfind by ID** (Get). Get one Hyperfind query by ID. all_details=true adds constraints.
- **UKG Dimensions hyperfinds execute** (Execute). Run a Hyperfind query for a date range and get the people it selects. Send hyperfind (id or qualifier) and dateRange (startDate and endDate, or symbolicPeriod).
Returns count and result (refs and basePersons). threshold caps the number of employees returned (default 3,500, up to 50,000). With enablePagination=true, send the returned nextReadToken as pageToken to get the next page.
Limits: at most 365 days, 10,000 employees and 10,000 locations per request.
- **List all UKG Dimensions data** (List). Run an Information Access (aggregated data) query: select Data Dictionary keys, from a view with an employeeSet (hyperfind or employees, plus dateRange) or locationSet, optional where filters, groupBy and sortBy.
Returns the whole response as one item: metadata (element totals, the cache key, and errors when a data provider hit its own limit) and data (a tree whose children are the rows).
To page, send index and count with options.requestTag and keep the body otherwise identical. Limits: at most 500 employees, 365 days, employees x days 10,000 and 300 locations.
- **List all UKG Dimensions data elements** (List). List every Data Dictionary element definition (key, label, categories, dataProvider, active, deprecated, properties). Use the keys in data.list queries. Not paginated.
- **UKG Dimensions data elements search** (Search). Get Data Dictionary element definitions for specific keys. The body is a JSON array of data element keys (strings). UKG does not publish a response schema for this operation.
- **List all UKG Dimensions pay codes** (List). List the pay codes available to the API user as a manager, or one pay code by id or qualifier. Not paginated. Access Control Point: PAY_CODE_NAME_LIST.
- **Get single UKG Dimensions pay code by ID** (Get). Get one pay code by ID. Only pay codes available to the API user are returned. Access Control Point: PAYCODE.
- **UKG Dimensions pay codes search** (Search). Get pay codes by reference: send where.payCodes with ids, qualifiers or refs. References that do not match a visible pay code come back as errors (207 partial success). Access Control Point: PAYCODE.
- **List all UKG Dimensions accrual codes** (List). List the accrual codes the API user can see, or one by id or qualifier. Returns id, name, shortName, typeId, typeName, hoursPerDayInSeconds, allowEdit and positionAware. Not paginated. Access Control Point: ACCRUALS_CONFIGURATION.
- **Get single UKG Dimensions accrual code by ID** (Get). Get one accrual code by ID.
- **List all UKG Dimensions accrual profiles** (List). List accrual profiles (GET /v3/timekeeping/setup/accrual_profiles), or one by id or qualifier. all_details=true returns full profiles (otherwise only ID and name); include_accrual_policies=true adds policies.
Truto pages this for you: pass limit and next_cursor, not index or count. Pages hold up to 100 profiles (the UKG default). UKG publishes no response model for this v3 operation. Access Control Point: ACCRUALS_CONFIGURATION.
- **List all UKG Dimensions work rules** (List). List the work rules available to the API user as a manager, or one by id or qualifier. Not paginated. Access Control Point: PAY_RULES.
- **List all UKG Dimensions pay rules** (List). List every timekeeping pay rule, or one by id or qualifier; all_details=false returns only IDs and names. Not paginated. Access Control Point: PAY_RULES.
- **List all UKG Dimensions timecards** (List). Get one employee's timecard as a manager. Pass employee_id or person_number, plus start_date and end_date or symbolic_period_id, and select the parts to return (such as PUNCHES, WORKED_SHIFTS, PAYCODE_EDITS, TOTALS, EXCEPTIONS); without select every part is returned. Returns one timecard record. For many employees use timecards.search.
- **UKG Dimensions timecards search** (Search). Get timecards for many employees (POST /v1/timekeeping/timecard/multi_read).
Send select (at most 10 entities recommended), where.employees or where.hyperFind, and where.dateRange (dates or symbolicPeriod). partial_success=true returns 207 with per-employee results instead of failing.
Limits: at most 500 employees, 365 days, and employees x days 28,000; UKG recommends at most 200 employees per pay period. Not paginated.
- **List all UKG Dimensions timecard metrics** (List). Get timecard metrics for many employees: select totals and summaries such as ACTUAL_TOTALS, SCHEDULED_TOTALS, PROJECTED_TOTALS, ACCRUAL_SUMMARY or ACCRUAL_TRANSACTIONS, with where.employeeSet (employees or hyperFindRef, plus dateRange).
Returns one record per employee. Limit: employees x days at most 280,000; UKG recommends at most 200 employees per pay period. partial_success=true returns 207 instead of failing. Not paginated.
- **List all UKG Dimensions timecard approvals** (List). List timecard approvals for one employee (person_num or employee_id) over start_date and end_date, or a symbolic period. Returns employee, approvingManager, approvalDate and isEmployeeApproved per approval. Not paginated.
- **List all UKG Dimensions punches** (List). Get punches in near real time for a datetime window (POST /v1/timekeeping/punches/apply_read). Send where.dateRange (startDateTime and endDateTime) and optionally where.employees.
Returns one record per employee: employee plus that employee's punches.
Truto pages this for you: pass limit and next_cursor, not index or count. limit counts employees per page: at most 25 by default (a tenant system setting can allow 1 to 50).
- **UKG Dimensions punches bulk import** (Import). Import punches for many employees (such as from time clocks). Send punches (each with employee, punchDtm and optional typeOverride, orgJob, commentsNotes), plus optional options and accrualValidationRequired. Returns the saved punches; a 207 response lists the failures.
- ...and 25 more tools. Call `tools/list` via the MCP endpoint, or see the full catalog via the API, for the complete set.