Connect UKG Dimensions to ChatGPT: Manage People & Global Records

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) 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 or explore our broader architectural overview on connecting UKG Dimensions to AI Agents.

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 requires you to write, test, and deploy new tool definitions.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for UKG Dimensions, connect it to ChatGPT, and execute complex workforce workflows using natural language.

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 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.

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.

{
  "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):

{
  "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.

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.

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.