---
title: "Connect UKG Dimensions to ChatGPT: Manage People & Global Records"
slug: connect-ukg-dimensions-to-chatgpt-manage-people-global-records
date: 2026-10-13
author: Riya Sethi
categories: ["AI & Agents"]
excerpt: "Learn how to connect UKG Dimensions to ChatGPT using a managed MCP server to automate timecards, schedules, and global workforce data without writing custom API code."
tldr: "Connect UKG Dimensions to ChatGPT via Truto's managed MCP server. This guide covers overcoming UKG API quirks, generating an MCP server, configuring ChatGPT, and building AI workforce workflows."
canonical: https://truto.one/blog/connect-ukg-dimensions-to-chatgpt-manage-people-global-records/
---

# Connect UKG Dimensions to ChatGPT: Manage People & Global Records

**UKG Dimensions in ChatGPT, in about a minute.** The best way to connect UKG Dimensions to ChatGPT is Elaichi: connect UKG Dimensions to Elaichi once, then add Elaichi to ChatGPT as a connector. Two steps, about a minute, with a 14-day free trial and no credit card required.

1. **Start your free trial.** Create your Elaichi account. 14 days free, no credit card required.
2. **Connect UKG Dimensions.** Connect UKG Dimensions once in Elaichi. ChatGPT never gets more access than you have.
3. **Add Elaichi to ChatGPT.** In ChatGPT, open Plugins, press +, and paste https://api.elaichi.ai/mcp into Server URL. Sign in and approve.

[Start free on Elaichi, 14 days, no credit card required](https://app.elaichi.ai/signup?utm_source=truto.one&utm_medium=referral&utm_campaign=launchpad&utm_content=post_markdown&utm_term=ukgdimensions) · [UKG Dimensions on Elaichi](https://elaichi.ai/connectors/ukgdimensions/?utm_source=truto.one&utm_medium=referral&utm_campaign=launchpad&utm_content=post_markdown&utm_term=ukgdimensions)

*Building UKG Dimensions into your own product? The guide below is for you.*

---

If you need to connect UKG Dimensions to ChatGPT to automate workforce management, process timecards, or handle complex labor scheduling, you need a [Model Context Protocol (MCP)](https://truto.one/what-is-mcp-model-context-protocol-the-2026-guide-for-saas-pms/) server. This server acts as a translation layer, mapping ChatGPT's JSON-RPC tool calls to the highly specific schemas of the UKG Dimensions API. You can either spend weeks building and maintaining this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL.

If your team uses Claude, check out our guide on [connecting UKG Dimensions to Claude](https://truto.one/connect-ukg-dimensions-to-claude-sync-schedules-time-tracking/) or explore our broader architectural overview on [connecting UKG Dimensions to AI Agents](https://truto.one/connect-ukg-dimensions-to-ai-agents-automate-leave-labor-flows/).

Giving a Large Language Model (LLM) read and write access to an enterprise workforce management system like UKG Dimensions is a significant engineering challenge. You have to handle unique pagination schemes, understand proprietary UKG concepts like Hyperfinds and Symbolic Periods, and parse bulk operation responses that return 207 Multi-Status codes instead of standard errors. Every time you want to expose a new UKG operation to your AI agent, a [custom MCP server](https://truto.one/how-to-build-mcp-servers-for-ai-agents-2026-hands-on-architecture-guide/) requires you to write, test, and deploy new [tool definitions](https://truto.one/auto-generated-mcp-tools-for-ai-agents-a-2026-architecture-guide/).

This guide breaks down exactly how to use Truto to generate a secure, [managed MCP server](https://truto.one/auto-generated-mcp-tools-for-ai-agents-a-2026-architecture-guide/) for UKG Dimensions, connect it to ChatGPT, and execute complex workforce workflows using natural language.

> Stop writing boilerplate API integration code. Let Truto generate secure, managed MCP servers for your AI agents in seconds.
>
> [Talk to us](https://truto.one/book-a-demo/)

## The Engineering Reality of the UKG Dimensions API

A custom MCP server is essentially a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, implementing it against UKG Dimensions is exceptionally painful for standard CRUD-oriented frameworks. 

If you decide to [build a custom MCP server](https://truto.one/how-to-build-mcp-servers-for-ai-agents-2026-hands-on-architecture-guide/) for UKG Dimensions, you own the entire API lifecycle. Here are the specific integration challenges that break standard REST assumptions when working with UKG:

### Hyperfinds and Two-Step Data Retrieval
In UKG Dimensions, you rarely query data by passing standard REST filters like `?department=sales`. Instead, UKG relies heavily on "Hyperfinds" - proprietary, saved queries configured within the tenant. To get timecards for a specific group of employees, an LLM cannot just request timecards with a filter. It must first execute a Hyperfind using the `ukg_dimensions_hyperfinds_execute` endpoint to retrieve a set of `personId` values, and then pass those specific identifiers into a subsequent multi-read request (like `ukg_dimensions_timecards_search`). Your MCP tool descriptions must explicitly teach the LLM this two-step operational pattern.

### Symbolic Periods Instead of Absolute Dates
UKG Dimensions heavily utilizes Symbolic Periods (e.g., `Current_Payperiod`, `Previous_Payperiod`) for scoping data requests. Many endpoints accept either absolute `startDate` and `endDate` parameters, or a `symbolicPeriod`. Because these periods depend on the specific tenant's payroll configuration and the API user's context, an AI agent cannot guess them. It must fetch the valid symbolic periods via the `list_all_ukg_dimensions_symbolic_periods` endpoint before attempting to retrieve timecards or schedules.

### Inconsistent Pagination Schemes
UKG Dimensions does not use a single, unified pagination strategy across its endpoints. Some endpoints (like `locations/multi_read` or `punches/apply_read`) use a cursor-based approach, which Truto automatically normalizes into standard `limit` and `next_cursor` arguments for the LLM. However, search endpoints (like `cost_centers/search` or `location_sets/search`) require a 0-based `index` and `count` sent in the request body, forcing the caller to request the next index until fewer than `count` records return. Building an MCP server requires hardcoding these different iteration strategies into your tool logic.

### The 207 Multi-Status Response Format
When executing bulk reads or bulk imports (such as importing pay code edits or querying timecards for 500 employees), UKG Dimensions often responds with HTTP 207 Multi-Status instead of HTTP 200 or 400. This means the overall network request succeeded, but individual records within the batch may have failed. Your MCP server must intercept these 207 responses, parse the complex nested arrays to find the `tkError` objects, and present them to the LLM in a structured format so the agent knows exactly which employee records failed and why.

## Step 1: Create the UKG Dimensions MCP Server

Before ChatGPT can call UKG Dimensions, you need an MCP server endpoint scoped to a specific integrated account. Truto allows you to generate this server dynamically.

You can create this server using either the Truto UI or programmatically via the Truto API.

### Method A: Via the Truto UI

If you are setting up a single connection for internal use, the UI is the fastest path.

1. Log into your Truto dashboard and navigate to **Integrated Accounts**.
2. Connect a new UKG Dimensions account or select an existing one.
3. Click the **MCP Servers** tab on the integrated account page.
4. Click **Create MCP Server**.
5. Select your configuration. You can filter the server to only allow `read` operations or specific tags (e.g., `timecards`, `persons`).
6. Copy the generated MCP server URL (it will look like `https://api.truto.one/mcp/a1b2c3d4...`).

### Method B: Via the Truto API

If you are building an application that programmatically deploys agents for your customers, use the API. Make a POST request to the `/mcp` endpoint for the specific `integrated_account_id`.

```bash
curl -X POST https://api.truto.one/integrated-account/$INTEGRATED_ACCOUNT_ID/mcp \
  -H "Authorization: Bearer $TRUTO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "UKG Dimensions ChatGPT Server",
    "config": {
      "methods": ["read", "write"],
      "tags": ["persons", "timecards", "schedules", "time_off"]
    }
  }'
```

The Truto API will validate that the integration has tools available, generate a secure token, and return a payload containing the `url`.

```json
{
  "id": "mcp_8a9b0c1d",
  "name": "UKG Dimensions ChatGPT Server",
  "config": {
    "methods": ["read", "write"],
    "tags": ["persons", "timecards", "schedules", "time_off"]
  },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67890"
}
```

Treat this URL as a secret. It encodes the tenant routing and authentication required to execute tools against the UKG API.

## Step 2: Connect the MCP Server to ChatGPT

Now that you have your secure MCP URL, you need to expose it to ChatGPT. You can do this through the ChatGPT UI (for personal or enterprise workspace use) or via a manual configuration file if you are using an MCP proxy architecture.

### Method A: Via the ChatGPT UI

This is the simplest way to add the tools directly to your ChatGPT interface.

1. Open ChatGPT and navigate to **Settings**.
2. Go to **Apps** -> **Advanced settings**.
3. Toggle on **Developer mode** (MCP support requires this feature flag, available on Pro, Plus, Business, Enterprise, and Education tiers).
4. Under **MCP servers / Custom connectors**, click to add a new server.
5. Set the **Name** to something descriptive (e.g., "UKG Dimensions Workforce").
6. Paste your Truto MCP URL into the **Server URL** field.
7. Click **Save**.

ChatGPT will immediately ping the endpoint, perform the JSON-RPC initialization handshake, and display the list of discovered UKG tools.

### Method B: Via Manual Config File (SSE Transport)

If you are running a local MCP proxy or testing with a desktop client that requires manual JSON configuration (similar to Claude Desktop's approach), you can use the `@modelcontextprotocol/server-sse` wrapper to bridge standard standard I/O to Truto's HTTP SSE endpoint.

Create or update your MCP config file (e.g., `mcp-config.json`):

```json
{
  "mcpServers": {
    "ukg_dimensions": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/a1b2c3d4e5f67890"
      ]
    }
  }
}
```

Restart your agent framework or desktop client. It will use the npx wrapper to establish a Server-Sent Events connection to Truto, fetching the UKG tools.

## Hero Tools for UKG Dimensions

Truto automatically derives tool definitions from the UKG Dimensions integration resources and documentation. Here are the highest-leverage operations for AI agents managing workforce data.

### 1. Execute a Hyperfind (`ukg_dimensions_hyperfinds_execute`)

Because UKG relies on saved queries to group employees, your agent will frequently need to run Hyperfinds to get a list of active `personId` records for a specific location or department before pulling timecards.

> "Run the 'Active Cashiers' hyperfind for the current pay period and give me the total count of employees returned."

### 2. Multi-Read Timecards (`ukg_dimensions_timecards_search`)

Fetching individual timecards one by one is too slow. This tool allows the agent to fetch timecards for multiple employees simultaneously. It handles the `207 Multi-Status` complexity natively.

> "Fetch the timecards for employee IDs 10452 and 10453 for the previous pay period. Show me their total worked hours."

### 3. Multi-Read Schedules (`ukg_dimensions_schedules_search`)

Retrieve the schedule of one or more employees or locations. The agent can select specific data modules to return, such as `SHIFTS`, `PAYCODEEDITS`, or `LEAVEEDITS`.

> "Get the schedule for the 'Downtown Branch' location for next week. Tell me who is covering the opening shift on Monday."

### 4. Create Time Off Request (`create_a_ukg_dimensions_time_off_request`)

Submit a time off request on behalf of an employee. The agent must provide the employee reference, the requested periods (dates and amounts), and the specific request subtype (e.g., Vacation, Sick Leave).

> "Submit a vacation request for employee 10452 for next Friday, taking 8 hours. Skip the accrual validation warnings."

### 5. Deep Employee Lookup (`get_single_ukg_dimensions_person_by_id`)

Fetch an employee's complete record, including their identity, job assignments, base wage rates, and gdap assignments. This requires the internal UKG `personId`, not the display `personNumber`.

> "Look up the full profile for person ID 88392. What is their primary labor account and base wage rate?"

### 6. Lightweight Directory Sync (`list_all_ukg_dimensions_persons`)

Retrieve a lightweight list of all persons in the tenant. This is paginated automatically by Truto using `limit` and `next_cursor`, bypassing UKG's internal pagination quirks. It returns basic fields like `firstName`, `lastName`, and `employmentStatus`.

> "List the first 50 employees in UKG. Filter for only those with an active employment status."

For the complete tool inventory, including endpoints for cost centers, labor categories, shift management, and bulk punch imports, view the [UKG Dimensions integration page](https://truto.one/integrations/detail/ukgdimensions).

## Workflows in Action

When you give ChatGPT access to the UKG Dimensions MCP server, it can orchestrate complex, multi-step workforce tasks automatically.

### Scenario 1: Auditing Timecards for Exceptions

Managers frequently need to review timecards at the end of a pay period to ensure there are no missed punches or unapproved overtime.

> "Review the timecards for the 'Warehouse Shift A' hyperfind for the Previous_Payperiod. Flag any employees who have exception markers or missed punches on their record."

**How the agent executes this:**
1. Calls `ukg_dimensions_hyperfinds_execute` passing `hyperfind: "Warehouse Shift A"` and `symbolicPeriod: "Previous_Payperiod"` to get the list of employee IDs.
2. Extracts the `personId` array from the response.
3. Calls `ukg_dimensions_timecards_search` passing the array of employees, the same symbolic period, and `select: ["EXCEPTIONS", "PUNCHES"]`.
4. Analyzes the returned timecard JSON payloads, identifies the exception markers, and formats a summarized report for the manager.

```mermaid
sequenceDiagram
    participant User
    participant Agent as "ChatGPT Agent"
    participant Truto as "Truto MCP Server"
    participant UKG as "UKG Dimensions API"

    User->>Agent: "Review timecards for 'Warehouse Shift A'..."
    Agent->>Truto: Call ukg_dimensions_hyperfinds_execute<br>{"hyperfind": "Warehouse Shift A"}
    Truto->>UKG: POST /v1/commons/hyperfind/execute
    UKG-->>Truto: Return employee references
    Truto-->>Agent: Return JSON array of personIds
    
    Agent->>Truto: Call ukg_dimensions_timecards_search<br>{"employees": [...], "select": ["EXCEPTIONS"]}
    Truto->>UKG: POST /v1/timekeeping/timecard/multi_read
    UKG-->>Truto: Return 207 Multi-Status timecards
    Truto-->>Agent: Return parsed timecard data
    Agent-->>User: Present list of flagged employees
```

### Scenario 2: Managing Leave Requests

Employees and managers need to check balances before submitting or approving leave. The agent can handle the verification and submission in one prompt.

> "Check the accrual balance for employee 99281. If they have at least 16 hours of PTO available, submit a time off request for them for next Thursday and Friday."

**How the agent executes this:**
1. Calls `list_all_ukg_dimensions_timeoff_accruals` for employee `99281` to fetch current balances.
2. Evaluates the response to confirm the PTO pay code has >= 16 hours.
3. Calls `list_all_ukg_dimensions_timeoff_request_subtypes` to find the exact ID for the PTO request subtype.
4. Calls `create_a_ukg_dimensions_time_off_request` passing the employee ID, the found subtype ID, and the date periods.
5. Reports the success and the created request ID to the user.

## Security and Access Control

When connecting an AI agent to sensitive HR and payroll data, you cannot rely solely on prompt engineering to prevent destructive actions. Truto MCP servers provide strict, server-side access controls.

When generating the MCP server URL (Step 1), you can apply the following configurations to limit the blast radius:

*   **Method Filtering (`config.methods`)**: Restrict the server to safe operations. Setting `methods: ["read"]` ensures the LLM can only execute `get` and `list` operations, physically blocking it from creating, updating, or deleting personnel records.
*   **Tag Filtering (`config.tags`)**: Scope the server to specific functional domains. Setting `tags: ["schedules", "timecards"]` hides all tools related to payroll, benefits, or cost centers, even if the underlying UKG API user has permissions for them.
*   **Secondary Authentication (`require_api_token_auth`)**: Enable this flag to force the ChatGPT client to pass a valid Truto API token in the `Authorization` header. This prevents unauthorized access even if the MCP URL is leaked.
*   **Time-to-Live (`expires_at`)**: Set an ISO datetime to automatically revoke the MCP server. This is ideal for granting temporary troubleshooting access to contractors or short-lived automated workflows.

## Handling Rate Limits and Upstream Errors

AI agents can generate requests at speeds much faster than human operators, quickly hitting UKG Dimensions' service limits (e.g., the 10,000 employees per request cap or the API Gateway rate limit). 

It is critical to understand that **Truto does not automatically retry, throttle, or apply backoff logic on rate limit errors.**

When UKG Dimensions returns an HTTP 429 Too Many Requests error, Truto passes that 429 error directly back to the ChatGPT agent. However, Truto transparently normalizes the upstream rate limit data into standard IETF headers (`ratelimit-limit`, `ratelimit-remaining`, `ratelimit-reset`). 

Your agent or client framework is entirely responsible for reading these headers and implementing its own retry-and-backoff logic. Do not build workflows assuming the MCP server will absorb and mask API throttling.

## Wrap Up

Connecting ChatGPT to UKG Dimensions via a custom-built integration requires mastering proprietary UKG concepts, normalizing messy pagination, and dealing with flat 207 Multi-Status responses. By leveraging Truto's auto-generated MCP servers, you eliminate the integration boilerplate entirely. You can securely scope access using methods and tags, hand the endpoint to ChatGPT, and immediately begin orchestrating complex workforce, scheduling, and timecard operations with natural language.