Merge Unified's UKG Pro WFM integration Merge Agent Handler's UKG Pro WFM MCP server

Connect your AI Agents to UKG Pro WFM in minutes

Merge lets you securely connect your agents to UKG Pro WFM and thousands of tools instantly

Start building for free

Read docs

UKG Pro WFM

Learn more about Merge Agent Handler

Available tools

list_leave_cases

List leave cases (extended absences) for a date range. Provide employeeids (the API requires an employee set for this query; use listpersons). Returns leave category, dates, and status. Optionally filter by status.

get_leave_case

Get a single leave case by ID. Returns leave category, dates, status, and employee. Use listleavecases to find valid leave case IDs.

create_leave_case

Create a new leave case for an employee. The leave category, reason, status, approvalStatus, and frequency object references are required by UKG, supply any not covered via additionalfields. Use listpersons for employee IDs.

list_accrual_balances

List accrual/PTO balances (per pay code) as of a given date. Provide employeeids (required; the API returns balances one employee at a time; use listpersons) AND a valid time-off request subtype via subtypename or subtypeid (required by the API; e.g. a configured subtype like 'Sick'). Returns pay code, balance, and as-of date.

list_persons

List persons (employees) in UKG Pro WFM as of an optional snapshot date. Returns person ID, person number, full name, and employment status. Use the index/cursor from page_info for the next page.

get_person

Get a single person's details by person ID. Returns name, job, location, hire date, and employment status. Use list_persons to find valid IDs.

create_person

Create a new person (employee) in UKG Pro WFM. Use listjobs and listlocations to find valid job and location IDs.

update_persons

Update one or more persons in UKG Pro WFM. Each update object must include a personIdentity (with personNumber or personKey) plus the changed attributes under personInformation. Use list_persons to find valid person numbers/keys.

list_jobs

List jobs (work roles) defined in UKG Pro WFM. Returns job ID, name, and status. Use these IDs when creating or updating persons and schedules.

list_locations

List work locations (org business structure) in UKG Pro WFM. Returns node ID, name, and full org path. Use these IDs when creating persons and schedules.

list_hyperfinds

List saved hyperfind employee queries in UKG Pro WFM. Returns query ID and name. Use execute_hyperfind to run a query and get the matching employees. Results are capped at count; reduce count or filter by visibility to see all — this endpoint has no pagination cursor.

execute_hyperfind

Execute a saved hyperfind query to get the matching employees. Returns a list of person references. Use list_hyperfinds to find valid hyperfind IDs.

list_schedules

List scheduled shifts for a date range and a set of employees. Returns shift start/end times, employee, and job. Provide employeeids (use listpersons).

create_schedule

Create a scheduled shift for an employee over a start/end datetime. Optionally set the job via jobid (use listjobs). Use listpersons for the employee ID. Location/cost-center transfers go via additionalfields.

delete_schedules

Delete one or more scheduled shifts for an employee by shift ID. Provide employeeid and shiftids. Use list_schedules to find valid shift IDs.

list_shift_swap_requests

List employee shift swap requests for a date range. Provide employeeids (required by the API; use listpersons). Returns requestor, recipient, shift details, and status. Optionally filter by status (e.g. SUBMITTED, APPROVED).

list_timecards

List timecards for a date range and a set of employees. Returns punches, worked shifts, and totals. Provide employeeids (use listpersons).

get_timecard

Get the timecard for a specific employee and date range. Returns punches, worked shifts, and totals. Use list_persons to find valid employee IDs.

update_timecard

Update a timecard for an employee over a date range. Supply timecarddata with the punch/paycode edits (e.g. {'punches': {'added': [...]}}). Use gettimecard to review first.

list_punches

List time punches (clock-in/out events) for a date range. Provide employeeids (required; use listpersons). Returns punch timestamp, employee, and transfer.

import_punches

Import time punches into UKG Pro WFM. Each punch must include punchDtm (ISO local datetime) and employee.qualifier (the employee's person number); optionally transfer.transferString.

validate_credential

Validate UKG Pro WFM credentials by making a lightweight authenticated API call. Returns success or a specific error message.

View all tools by creating a free account See more tools

How to set up Merge Agent Handler

In an mcp.json file, add the configuration below, and restart Cursor.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5      "headers": {
6        "Authorization": "Bearer yMt*****"
7      }
8    }
9  }
10}
11

Copy Code

Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.

Make sure Claude is using the Node v20+.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "command": "npx",
5      "args": [
6        "-y",
7        "mcp-remote@latest",
8        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9        "--header",
10        "Authorization: Bearer ${AUTH_TOKEN}"
11      ],
12      "env": {
13        "AUTH_TOKEN": "yMt*****"
14      }
15    }
16  }
17}

Copy Code

Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.

Learn more in the official documentation ↗

1{
2    "mcpServers": {
3      "agent-handler": {
4        "command": "npx",
5        "args": [
6          "-y",
7          "mcp-remote@latest",
8          "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9          "--header",
10          "Authorization: Bearer ${AUTH_TOKEN}"
11        ],
12        "env": {
13          "AUTH_TOKEN": "<ah-production-access-key>"
14        }
15      }
16    }
17  }

Copy Code

In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".

You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.

Learn more in the official documentation ↗

1{
2  "inputs": [
3    {
4      "type": "promptString",
5      "id": "agent-handler-auth",
6      "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7      "password": true
8    }
9  ],
10  "servers": {
11    "agent-handler": {
12      "type": "stdio",
13      "command": "npx",
14      "args": [
15        "-y",
16        "mcp-remote@latest",
17        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18        "--header",
19        "Authorization: Bearer ${input:agent-handler-auth}"
20      ]
21    }
22  }
23}

Copy Code

FAQs on using Merge's UKG Pro WFM MCP server

Explore other MCP servers built and managed by Merge

FireHydrant

Foursquare

Frame.io

FreshBooks

Freshdesk

Freshservice

Front

Gamma

GitHub

GitLab

Gmail

Gong

Google Analytics

Google BigQuery

Google Calendar

Google Docs

Google Drive

Google Maps

Google Meet

Google Sheets

Google Slides

Google Tasks

Grafana

Greenhouse

Ready to try it out?

Whether you're an engineer experimenting with agents or a product manager looking to add tools, you can get started for free now