Connect UKG Ready to ChatGPT: Manage Payroll & Employee Data

If you need to connect UKG Ready to ChatGPT to automate HR workflows, query payroll discrepancies, or manage employee schedules, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between ChatGPT's tool calls and UKG Ready's highly relational REST APIs. 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 Claude, check out our guide on connecting UKG Ready to Claude or explore our broader architectural overview on connecting UKG Ready to AI Agents.

Giving a Large Language Model (LLM) read and write access to a complex Human Capital Management (HCM) system like UKG Ready is a serious engineering challenge. You have to handle company shortname (CID) propagation, navigate deprecated v1 endpoints, and ensure that the LLM understands subsystem dependencies before making state-changing calls. Every time a new custom HR field is added or a subsystem is toggled, a custom-built server requires manual code updates and redeployments.

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

The Engineering Reality of the UKG Ready API

A custom MCP server is essentially a self-hosted API proxy layer. While the open MCP standard provides a predictable way for LLMs to discover tools via JSON-RPC, implementing it against UKG Ready's enterprise API surface is exceptionally painful.

If you decide to build a custom MCP server for UKG Ready, you own the entire API lifecycle. Here are the specific integration challenges that break standard CRUD assumptions when working with this HCM platform:

The Subsystem Dependency Trap

Unlike flat REST APIs where endpoints are universally available, UKG Ready is modular. Many endpoints will simply throw errors if the corresponding subsystem - such as TLM (Time and Labor Management), HR, or SCHEDULE - is not enabled for that specific company. If an LLM tries to call /v2/companies/{cid}/schedules without the Advanced Scheduler subsystem active, the call fails. Your custom MCP server must be smart enough to detect active subsystems and dynamically expose or hide MCP tools to prevent the LLM from hallucinating capabilities it cannot execute.

The CID (Company ID) Propagation Problem

UKG Ready is fundamentally multi-tenant at the API layer. Almost every endpoint requires a cid (Company Shortname) parameter to function. When building a custom MCP server, you must either hardcode the CID, extract it dynamically from the initial authentication context, or force the LLM to provide it in every single tool call. If you force the LLM to provide it, the model will inevitably guess or hallucinate the string. Truto handles context propagation securely, ensuring the correct account bindings are applied before the proxy API executes the call.

The v1 to v2 Deprecation Minefield

UKG Ready has a massive surface area, and much of it is mid-migration. For example, endpoints like list_all_ukg_ready_employees_v_1 are deprecated in favor of v2 companies employees. If you build your own tools from scratch by parsing standard API docs, you risk mapping to endpoints that will soon return 410 Gone errors. Truto curates the documentation records, meaning the dynamically generated tools map to the correct, modern v2 REST definitions without requiring you to write routing logic.

Transparent Rate Limit Handling

UKG Ready enforces strict rate limits to protect its multi-tenant environment. It is a common misconception that integration middleware should automatically retry and absorb HTTP 429 Too Many Requests errors. Truto takes a deterministic approach: it does not retry, throttle, or apply backoff on rate limit errors. Instead, when the upstream UKG Ready API returns an HTTP 429, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit info into standardized IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). This places the responsibility of retry logic and backoff directly on the LLM runtime or orchestration framework, where contextual decisions about prompt pausing can actually be made.

How to Generate a Secure UKG Ready MCP Server

Truto dynamically generates MCP tools based on the integration's documented resources and methods. You do not need to write JSON-RPC tool schemas. You can generate an MCP server scoped to a specific UKG Ready account using either the Truto UI or the API.

Method 1: Via the Truto UI

If you are manually setting up an agent environment, the UI provides the fastest path to a working server.

1. Log into your Truto dashboard and navigate to the Integrated Accounts section.
2. Select your connected UKG Ready account.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Configure the server parameters (e.g., restrict to read methods, filter by payroll tags, and set an optional expiration date).
6. Click Save and copy the generated MCP server URL (it will look like https://api.truto.one/mcp/<token>).

Method 2: Via the Truto API

For production use cases where you need to programmatically provision agent environments on behalf of your users, you should use the REST API.

Make a POST request to /integrated-account/:id/mcp. This scopes the server securely to that specific tenant's connection.

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 Ready Payroll Agent",
    "config": {
      "methods": ["read", "write"],
      "tags": ["employees", "payroll", "time_tracking"]
    }
  }'

The response will contain a url property containing the secure token. This single URL carries the cryptographic routing instructions needed to authenticate and execute API calls against UKG Ready.

How to Connect the MCP Server to ChatGPT

Once you have your Truto MCP URL, you can plug it directly into ChatGPT. The model will send an initialize request, discover the UKG Ready tools, and begin routing natural language queries into executable API operations.

Method A: Via the ChatGPT UI

If you are using ChatGPT Pro, Plus, Enterprise, or Education, you can add custom MCP endpoints directly from the settings menu.

1. In ChatGPT, navigate to Settings -> Apps -> Advanced settings.
2. Enable the Developer mode toggle (MCP support requires this flag to be active).
3. Under MCP servers / Custom connectors, click to add a new server.
4. Set the Name to something recognizable, like "UKG Ready HCM".
5. Paste the Truto MCP URL into the Server URL field.
6. Save the configuration. ChatGPT will immediately perform a handshake and pull the tool schemas.

Method B: Via Manual Config File (SSE Transport)

If you are using an orchestration framework, a custom desktop client, or connecting via a local agent interface that supports the standard JSON config structure, you can use the Server-Sent Events (SSE) proxy command.

Create an mcp.json (or similarly named config file for your client) that uses the @modelcontextprotocol/server-sse CLI wrapper to connect to the remote Truto URL.

{
  "mcpServers": {
    "ukg-ready": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/<your-token-here>"
      ]
    }
  }
}

When the agent boots up, it invokes the node wrapper to establish an SSE connection, translating local standard I/O into the remote HTTP requests required by the Truto MCP router.

Hero Tools for UKG Ready

Truto provides dozens of endpoints for UKG Ready. When you expose this integration via MCP, these endpoints become callable tools. Here are the highest-leverage tools for automating HR and payroll workflows.

list_all_ukg_ready_employees

This is the core discovery tool. It lists all employees the authenticated user has permission to view. This is critical because almost all other operations in UKG Ready (time tracking, accruals, deductions) require the internal id or employee_id returned by this operation. It requires the cid parameter.

"Find the employee record for Sarah Connor and get her internal UKG Ready ID. We need this to check her payroll deductions later."

list_all_ukg_ready_employee_accrual_balances_v_2

This tool queries the modern v2 accruals module to check an employee's time-off balances. It returns a detailed breakdown of accrued time, taken time, and the current balance. It requires the cid and employee_id.

"Check the current PTO and sick leave accrual balances for employee ID 554321 as of today."

create_a_ukg_ready_employee_ptorequest

Agents can execute write operations using this tool to submit time-off requests. It accepts structured data detailing the dates, the type of request (FullDay, Partial, Multiple), and the target employee. This allows ChatGPT to act as an HR self-service interface.

"Submit a full-day time-off request for employee 554321 for next Friday. Use their standard vacation accrual bucket."

list_all_ukg_ready_company_payrolls

This tool retrieves the list of company payrolls that are available for processing. It returns the status of each payroll run (e.g., Open, Closed, Finalized), pay dates, and start/end dates. This is essential for agents performing payroll audits.

"List all the open payroll runs for our company. I need to know the start and end dates for the current pay period before we sync time entries."

list_all_ukg_ready_employee_time_entries

This pulls the timesheet data for a specific employee within a given date range (maximum 31 days). It is the backbone for workflows that audit hours worked against scheduled shifts to calculate overtime or identify anomalies.

"Pull all the time entries for employee 554321 from the 1st of this month to today. Sum up the total hours worked and highlight any entries exceeding 8 hours in a single day."

ukg_ready_employee_schedules_bulk_update

This tool allows you to mass-update an employee's schedule for a specified date range. It replaces existing schedule blocks, making it highly effective for AI agents tasked with balancing shift coverage or responding to last-minute sick leave.

"Update the schedule for employee 554321 for next Monday through Wednesday. Assign them to the 9 AM to 5 PM shift block."

To view the complete schema details and the full list of available operations, check out the UKG Ready integration page.

Workflows in Action

Once connected, ChatGPT can sequence these tools to solve complex, multi-step HR and payroll problems. The LLM handles the logic and parameter extraction, while the Truto MCP server executes the API calls.

Workflow 1: Pre-Payroll Time Card Audit

Payroll administrators spend hours manually checking timesheets for anomalies. You can instruct ChatGPT to perform this audit automatically.

"Audit the time entries for John Doe for the current open payroll period. Find his employee record, identify the dates of the open payroll, pull his time entries, and flag any day where he logged more than 10 hours."

Execution Steps:

1. list_all_ukg_ready_employees: The agent searches for "John Doe" to extract his internal id.
2. list_all_ukg_ready_company_payrolls: The agent fetches the list of payrolls to find the start and end dates of the Open payroll run.
3. list_all_ukg_ready_employee_time_entries: Using the employee ID and the date range from the payroll run, the agent fetches the specific time punches.

Outcome: ChatGPT processes the JSON array of time entries, sums the hours per day, and returns a formatted summary of any overtime risks directly in the chat interface.

sequenceDiagram
  participant User as User
  participant GPT as ChatGPT
  participant MCP as Truto MCP Server
  participant UKG as "Upstream API (UKG Ready)"

  User ->> GPT: "Audit John Doe's time entries for the open payroll."
  GPT ->> MCP: tools/call - list_all_ukg_ready_employees
  MCP ->> UKG: GET /v2/companies/{cid}/employees?name=John Doe
  UKG ->> MCP: Returns Employee ID 1042
  MCP ->> GPT: ID 1042
  
  GPT ->> MCP: tools/call - list_all_ukg_ready_company_payrolls
  MCP ->> UKG: GET /v2/companies/{cid}/payrolls
  UKG ->> MCP: Open Payroll: Jan 1 - Jan 15
  MCP ->> GPT: Dates: Jan 1 - Jan 15
  
  GPT ->> MCP: tools/call - list_all_ukg_ready_employee_time_entries
  MCP ->> UKG: GET /v2/companies/{cid}/employees/1042/time-entries
  UKG ->> MCP: Time punch data
  MCP ->> GPT: Time punch data
  
  GPT ->> User: "Audit complete. John logged 11 hours on Jan 4."

Workflow 2: Automated PTO Request and Schedule Adjustment

Handling sudden time-off requests requires interacting with multiple HR subsystems. ChatGPT can act as a manager assistant to process these requests.

"Check if Sarah Connor has enough PTO for next Thursday and Friday. If she does, submit the time-off request and clear her schedule for those days."

Execution Steps:

1. list_all_ukg_ready_employees: The agent locates Sarah Connor's internal ID.
2. list_all_ukg_ready_employee_accrual_balances_v_2: The agent checks her vacation balance to ensure it exceeds 16 hours.
3. create_a_ukg_ready_employee_ptorequest: The agent submits the formal time-off request to the UKG Ready system for approval.
4. ukg_ready_employee_schedules_bulk_delete: The agent proactively removes her from the active shift roster for those dates.

Outcome: The agent confirms to the manager that the PTO is submitted, the balance was sufficient, and the shift blocks are now vacant and ready for reallocation.

Security and Access Control

Giving an LLM access to sensitive payroll and personnel data requires strict boundaries. Truto MCP servers support configuration parameters that lock down what an agent can see and do.

• Method Filtering: Use the config.methods array (e.g., ["read"]) to restrict the agent to non-destructive operations. If an agent tries to call a create or update tool on a read-only server, the call is rejected before it reaches UKG Ready.
• Tag Filtering: Use the config.tags array (e.g., ["time_tracking"]) to limit the server's scope. An agent scoped to time tracking will not even know that payroll deduction tools exist.
• require_api_token_auth: By default, the MCP URL acts as a bearer token. Setting this flag to true requires the caller to also pass a valid Truto API token in the HTTP Authorization header, adding a strict secondary authentication layer.
• expires_at: You can append an ISO datetime to automatically terminate the MCP server. This is perfect for granting temporary agent access for a specific audit task.

Moving Past Manual Integration Maintenance

Connecting UKG Ready to ChatGPT transforms how organizations handle HCM workflows, moving away from rigid UI dashboards toward natural language orchestration. However, building this connectivity manually forces your engineering team into a perpetual cycle of reading API updates, wrestling with deprecated v1 endpoints, and mapping complex subsystem dependencies.

By leveraging an auto-generated MCP server, you abstract away the REST boilerplate. The LLM focuses on workflow logic, the MCP server handles protocol translation and contextual authentication, and your engineers focus on building your core product.

Ready to give your AI agents access to UKG Ready? Book a demo with Truto and spin up your first MCP server in minutes.