Connect your AI Agents to UKG Pro WFM in minutes
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.
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}
11Open 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}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 }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}FAQs on using Merge's UKG Pro WFM MCP server
FAQs on using Merge's UKG Pro WFM MCP server
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
