Connect UKG Dimensions to Claude: Sync Schedules & Time Tracking

If your team needs to connect UKG Dimensions to Claude to automate shift scheduling, audit timecards, or handle complex time-off approvals, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's natural language tool calls and the sprawling UKG Dimensions REST API. You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL. If your team uses ChatGPT, check out our guide on connecting UKG Dimensions to ChatGPT or explore our broader architectural overview on connecting UKG Dimensions to AI Agents.

Giving a Large Language Model (LLM) read and write access to a monolithic workforce management system like UKG Dimensions is an engineering challenge. You have to handle session lifecycles, map massive nested JSON schemas to MCP tool definitions, and deal with UKG's highly specific query patterns and combinatorial data limits. Every time an API version shifts or a data dictionary element changes, you have to update your server code, redeploy, and test the integration.

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

The Engineering Reality of the UKG Dimensions API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against specialized enterprise APIs is painful. UKG Dimensions is built to handle global payroll rules, dynamic labor scheduling, and complex accrual profiles. Its API reflects that immense complexity.

If you decide to build a custom UKG Dimensions MCP server, here are the specific integration challenges you will face:

Combinatorial Service Limits UKG Dimensions enforces strict rate limiting and response constraints, but they are rarely simple row counts. For timecards and schedules, limits are often calculated multiplicatively. For example, the timecards.search endpoint limits requests to employees x days = 28,000. The schedules.search limit is employees x days = 56,000. If an LLM attempts to pull a year of timecards for 100 employees, the API will reject it (100 x 365 = 36,500). Your MCP tools must explicitly document these limits in the schema so the LLM knows to chunk its requests.

Complex POST-based Search Operations Unlike standard REST APIs that use GET requests with query parameters for filtering, UKG Dimensions heavily relies on POST /multi_read operations with deeply nested where clauses. Finding a person requires passing an employeeSet containing jobassignmentid, personnumber, or badgenumber. Truto abstracts these payloads into strongly typed JSON schemas within the MCP tool definitions, preventing the LLM from hallucinating standard REST syntax.

Destructive Hard Deletes vs Effective Dating The UKG API handles offboarding differently depending on the endpoint. Calling delete on a person record executes a permanent hard delete of the employee, their timekeeping, and schedule data. It is only permitted for inactive employees outside the current pay period. To simply offboard an employee, you must execute a PUT update to change their employment status to an effective-dated Terminated status. An unguided LLM could inadvertently wipe out compliance data if given unfettered delete access.

Step 1: Create the UKG Dimensions MCP Server

Truto dynamically generates MCP servers for any connected UKG Dimensions account. These servers translate UKG's complex resources and data dictionaries into LLM-friendly tools.

You can create an MCP server in Truto using either the dashboard UI or the REST API.

Method 1: Via the Truto UI

1. Navigate to the Integrated Accounts page in the Truto dashboard.
2. Select your connected UKG Dimensions account.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your configuration - name the server, filter allowed methods (e.g., read only), and optionally set an expiration date.
6. Click Save and copy the generated MCP Server URL.

Method 2: Via the Truto API

For automated deployments, you can provision an MCP server programmatically by sending a POST request to Truto's unified API. This provisions a secure token and returns the connection URL.

curl -X POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Claude UKG Dimensions Server",
    "config": {
      "methods": ["read", "write"]
    }
  }'

The response contains the secure URL you will provide to Claude:

{
  "id": "mcp_srv_778899",
  "name": "Claude UKG Dimensions Server",
  "url": "https://api.truto.one/mcp/abc123def456...",
  "expires_at": null
}

Step 2: Connect the MCP Server to Claude

Once you have your Truto MCP URL, you need to register it with your AI client. You can do this through the Claude application UI or by modifying your system's configuration files.

Method A: Via the Claude UI (Claude for Work / Enterprise)

If your organization has enabled custom integrations in the Claude UI:

1. Open Claude and navigate to Settings.
2. Click on Integrations (or Connectors depending on your plan).
3. Select Add MCP Server.
4. Paste the Truto MCP URL (https://api.truto.one/mcp/...).
5. Click Add. Claude will automatically perform the initialization handshake and ingest the UKG tools.

Method B: Via the Claude Desktop Configuration File

For local development or standalone Claude Desktop usage, you can map the remote Truto server using the standard Server-Sent Events (SSE) transport. Truto provides a helper package (@modelcontextprotocol/server-sse) that bridges the local Claude client to the remote Truto URL.

Edit your Claude desktop configuration file.

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the UKG Dimensions server mapping:

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

Restart Claude Desktop. The application will execute the npx command to establish the connection, allowing Claude to instantly see all available UKG tools.

Hero Tools for UKG Dimensions

Truto exposes the entirety of the UKG Dimensions API as AI-ready tools. Here are the highest-leverage operations for workforce and time tracking workflows.

1. list_all_ukg_dimensions_persons

Retrieves a lightweight directory of employees. This is typically the first tool the agent calls to resolve a user's name to their UKG personId (also known as the employee ID), which is required for almost all subsequent operations.

"Find the UKG employee ID for Jane Doe and verify her current employment status."

2. get_single_ukg_dimensions_person_by_id

Fetches the complete profile for a specific employee using their personId. The payload includes names, contacts, primary labor accounts, base wage rates, and user account status.

"Pull the complete employee profile for person ID 10984, including their primary labor account and base wage rate."

3. ukg_dimensions_schedules_search

Extracts shift schedules for multiple employees or locations over a specific date range. It uses a POST operation where the agent can specify select options like SHIFTS, PAYCODEEDITS, and LEAVEEDITS. The agent must manage the employees x days < 56000 limit.

"Pull the scheduled shifts for the warehouse team hyperfind next week. Only return shift data, no leave edits."

4. ukg_dimensions_timecards_search

Extracts detailed timecard data in bulk. This is critical for overtime audits and payroll discrepancy checks. The agent configures the select array to fetch specific entities like PUNCHES, TOTALS, or EXCEPTIONS.

"Retrieve last week's timecards for employees 4451 and 4452. Include their raw punches and any timecard exceptions."

5. list_all_ukg_dimensions_time_off_requests

Searches time-off requests based on a specific employeeRef, hyperfind, or dateRange. Useful for managers checking coverage before approving new leave requests.

"List all approved time-off requests for the engineering department next month to check our coverage."

6. create_a_ukg_dimensions_time_off_request

Submits a new PTO request for an employee. The agent must formulate the timeOffRequest object, requiring the employee ID, periods, and the correct requestSubType.

"Draft a time off request for John Smith for next Friday using the 'Vacation' subtype. Do not skip accrual validation."

To view the complete schema definitions and the full list of available UKG tools, visit the UKG Dimensions integration page.

Workflows in Action

When Claude is equipped with Truto's UKG Dimensions MCP server, it can orchestrate complex, multi-step workforce tasks completely autonomously.

Scenario 1: Auditing Timecard Exceptions & Overtime

Managers spend hours manually hunting down missed punches and unscheduled overtime. Claude can automate this entirely.

"Audit last week's timecards for the night shift team (Hyperfind ID 883). Flag any employees who have missed punches or exceeded 40 hours, and summarize their exceptions."

How the agent executes this:

1. Calls ukg_dimensions_hyperfinds_execute passing ID 883 and the date range to get the list of relevant personIds.
2. Calls ukg_dimensions_timecards_search passing the retrieved personIds, the date range, and setting select to ["PUNCHES", "TOTALS", "EXCEPTIONS"].
3. Claude analyzes the resulting JSON, isolates employees with exception flags (like missed out-punches) or TOTALS indicating overtime, and formats a human-readable summary table.

sequenceDiagram
    participant User as User
    participant Claude as Claude Desktop
    participant Truto as Truto MCP Server
    participant UKG as UKG API
    User->>Claude: "Audit timecards for team 883..."
    Claude->>Truto: Call ukg_dimensions_hyperfinds_execute
    Truto->>UKG: POST /v1/hyperfind/execute
    UKG-->>Truto: Return employee IDs
    Truto-->>Claude: JSON array of personIds
    Claude->>Truto: Call ukg_dimensions_timecards_search (PUNCHES, TOTALS)
    Truto->>UKG: POST /v1/timekeeping/timecard/multi_read
    UKG-->>Truto: Return timecard data
    Truto-->>Claude: JSON timecards
    Claude-->>User: Present formatted audit report

Scenario 2: Managing Leave Conflicts

Employees frequently ask for time off without checking team capacity. Claude can act as an intelligent scheduling assistant, checking balances and overlaps before generating the request.

"I am Sarah Connor. I want to take a vacation on October 12th. Check if I have enough accrued time, verify that nobody else on my team is off that day, and if we are clear, submit the request."

How the agent executes this:

1. Calls list_all_ukg_dimensions_persons searching for "Sarah Connor" to get her personId.
2. Calls list_all_ukg_dimensions_timeoff_accruals to verify her current vacation balance.
3. Calls list_all_ukg_dimensions_person_supervisors and ukg_dimensions_hyperfinds_execute to determine her immediate team context.
4. Calls list_all_ukg_dimensions_time_off_requests passing the team's IDs for October 12th to check for overlapping approved leave.
5. If the schedule is clear and balances suffice, calls create_a_ukg_dimensions_time_off_request to submit the PTO request.
6. Reports the successful confirmation back to the user.

Security and Access Control

Exposing workforce identity and payroll data to an LLM requires strict boundary enforcement. Truto's MCP servers provide fine-grained controls baked directly into the URL token.

• Method filtering: You can enforce read-only access by passing methods: ["read"] during server creation. The LLM will only see get and list tools, physically preventing it from creating shifts or deleting records.
• Tag filtering: If you only want the LLM to access scheduling data but not payroll rates, use tags to restrict the exposed tools to specific UKG resource categories.
• Expiration limits: By setting expires_at, you can generate temporary access tokens. Truto automatically destroys the token and drops the connection at the exact timestamp, ideal for contractor LLM workflows.
• Extra authentication: For high-security environments, setting require_api_token_auth: true forces the MCP client to also pass a valid Truto API token in the headers, meaning a leaked URL alone cannot be used.

Handling Rate Limits and Errors

It is vital to understand how Truto handles UKG Dimensions' strict rate limits. 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 error directly back to the calling LLM framework. However, Truto does normalize the upstream rate limit data into standardized IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset).

Your AI agent framework (like LangChain, LangGraph, or custom Claude loops) is responsible for reading these headers, pausing execution, and applying exponential backoff before retrying the tool call. This ensures your agent retains full control over execution timing rather than timing out unexpectedly inside a black-box middleware layer.

Orchestrate Your Workforce with AI

Connecting Claude to UKG Dimensions transforms workforce management from a tedious, UI-bound chore into a dynamic, conversational experience. With Truto's managed MCP architecture, you completely bypass the pain of reverse-engineering UKG's multi_read operations, deciphering pagination logic, or writing custom auth wrappers.

You generate the URL, connect the model, and let Claude handle the heavy lifting. By bridging the reasoning power of modern LLMs with the operational depth of UKG Dimensions, you empower managers and employees to focus on their actual work - not the software that tracks it.