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

Connect your AI Agents to UKG Pro in minutes

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

Start building for free

Read docs

UKG Pro

Learn more about Merge Agent Handler

Available tools

list_companies

List company details from UKG Pro with pagination. Returns company names, IDs, addresses, and other company configuration data.

get_company

Get a specific company by ID. Returns company name, address, and configuration details. Use list_companies to find valid IDs.

list_compensation_details

List compensation details from UKG Pro with pagination. Returns salary, pay rate, pay frequency, and other compensation data for all employees.

get_compensation_details

Get compensation details for a specific employee by ID. Returns salary, pay rate, pay frequency, and other compensation data.

list_employee_demographics

List employee demographic details from UKG Pro with pagination. Returns names, addresses, contact info, and other demographic data. Use page and per_page for pagination.

get_employee_demographics

Get demographic details for a specific employee by ID. Returns name, address, contact info, and other demographic data.

list_person_details

List person details from UKG Pro with pagination. Returns personal information including date of birth, gender, ethnicity, and other person-level data.

get_person_details

Get person details for a specific employee by ID. Returns personal information including date of birth, gender, ethnicity, and other person-level data.

list_employment_details

List employment details from UKG Pro with pagination. Returns hire date, status, job title, department, and other employment data for all employees.

get_employment_details

Get employment details for a specific employee by ID. Returns hire date, status, job title, department, and other employment data.

list_job_history

List employee job history details from UKG Pro with pagination. Returns job changes, promotions, transfers, and other employment history records.

get_employee_job_history

Get job history for a specific employee by ID. Returns all job changes, promotions, transfers, and other employment history records for the employee.

list_employee_changes

List employee changes from UKG Pro with pagination. Returns recent changes to employee records including new hires, terminations, and data updates.

list_locations

List locations from UKG Pro with pagination. Returns location names, addresses, codes, and other location configuration data.

get_location

Get a specific location by ID. Returns location name, address, and configuration details. Use list_locations to find valid IDs.

list_org_levels

List organization levels from UKG Pro with pagination. Returns org level codes, names, and hierarchy data used to define the organizational structure.

get_org_level

Get a specific organization level by code. Returns org level name, hierarchy, and configuration details. Use listorglevels to find valid codes.

list_positions

List positions from UKG Pro with pagination. Returns position codes, titles, departments, and other position configuration data.

get_position

Get a specific position by position code. Returns position title, department, and configuration details. Use list_positions to find valid codes.

list_pto_plans

List PTO plans from UKG Pro with pagination. Returns all PTO plan configurations including plan names, accrual rates, and balances.

get_employee_pto_plans

Get PTO plans for a specific employee. Requires company ID and employee ID. Use list_companies to find the company ID.

validate_credential

Validate UKG Pro credentials. Verifies the service domain, username, password, and Customer API key are correct by making a test API call.

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 MCP server

What is a UKG Pro MCP?

A UKG Pro MCP server connects your agents to employee and workforce data through a set of callable tools. Your agents can invoke these tools to retrieve person and employment records, pull compensation details, track org structure changes, query PTO plans, and more.

UKG doesn't offer an MCP server purpose built for UKG Pro, but you can use one from a third-party platform, like Merge Agent Handler.

How can I use the UKG Pro MCP server?

The use cases naturally depend on the agent you've built, but here are a few common ones:

Employee directory sync: When a new hire completes onboarding in your ATS, an agent pulls their person and employment details from UKG Pro and pushes a corresponding profile to the company directory tool, keeping both systems in sync without manual data entry

PTO balance lookup from Slack: When an employee asks a Slack bot about their remaining time off, an agent queries UKG Pro for their PTO plan and current balance, then replies directly in the thread with the current figure

Org chart updates on reporting changes: When a manager reassignment is recorded in UKG Pro, an agent detects the change via employee change tracking, retrieves the updated org level data, and pushes the new reporting structure to the company's org chart tool

Compensation reporting for finance: On a scheduled basis, an agent pulls compensation details for a defined employee cohort from UKG Pro and posts a structured summary to a finance Slack channel, giving stakeholders current data without requiring direct system access

What are popular tools for UKG Pro's MCP server?

Here are some of the most commonly used tools:

list_person_details: retrieves core employee records including name, contact information, and personal identifiers for employees across the organization. Useful for agents that need a complete employee roster before syncing data to another system

list_employment_details: returns employment information such as hire date, status, job title, and work location for each employee. Call this when an agent needs employment context before creating or updating a record in a downstream tool

list_compensation_details: fetches compensation data including pay rate, pay type, and effective dates. Good for workflows that generate finance reports or need to verify comp data before a payroll-adjacent process runs

list_employee_changes: returns a log of recent employee record changes across fields like manager, location, title, and status. Use this when an agent needs to detect what changed and react accordingly rather than polling individual records

list_org_levels: retrieves the organizational hierarchy levels defined in UKG Pro. Helpful when an agent needs to map reporting structures before building or updating an org chart in another tool

get_employee_pto_plans: returns the PTO plan assignments and balances for a specific employee. Call this when an agent needs to respond to a time-off inquiry or verify eligibility before taking an action in a scheduling tool

What makes Merge Agent Handler's UKG Pro MCP server better than alternative UKG Pro MCP servers?

UKG Pro holds some of the most sensitive data in your organization, which makes several aspects of Merge Agent Handler especially relevant:

Enterprise-grade security and DLP: Merge Agent Handler includes built-in data loss prevention controls that let you block or redact sensitive fields before they reach an agent. For UKG Pro, this means you can prevent compensation figures, personal contact details, or employment status from being surfaced to agents that don't need that level of access

Managed authentication and credentials: Merge stores and refreshes your UKG Pro API credentials on your behalf. You never pass raw credentials to an agent or deal with expired tokens breaking a workflow mid-run

Real-time observability and audit trail: Every UKG Pro tool call is logged with the timestamp, tool name, input parameters, and response metadata. You can see exactly which employee records an agent read or which org changes it processed, with no custom instrumentation required

Tool Packs and controlled access: Tool Packs let you scope exactly which UKG Pro tools each agent can reach. For example, a directory sync agent can get access to list_person_details and list_employment_details but never gets access to list_compensation_details, or other fields it has no reason to read

How can I start using Merge Agent Handler's UKG Pro MCP server?

You can take the following steps:

1. Create or log into your Merge Agent Handler account.

2. Install the Merge CLI by running pipx install merge-api, then run merge configure to link the CLI to your Merge account and merge login to authenticate your session.

3. Register the Agent Handler MCP server with Claude Code by running claude mcp add --transport http agent-handler https://ah-api.merge.dev/mcp, then open Claude Code and run /mcp to confirm agent-handler appears with a connected status.

4. Select agent-handler from the MCP list. This opens a browser window where you select which integrations to authenticate. Choose UKG Pro and complete the credential setup. Merge stores and manages the credentials going forward.

5. Open a Claude Code session and start querying UKG Pro data directly. The first time you use a UKG Pro tool, a Magic Link may appear to complete connector authentication.

If you want to connect Merge Agent Handler's UKG Pro MCP with internal or customer-facing agentic products, you can follow the steps in our docs.

Can employees use Merge Agent Handler to connect their AI tools to UKG Pro?

Yes, Agent Handler for Employees lets your employees connect Claude, ChatGPT, Microsoft Copilot, Cursor, and other MCP-compatible AI tools to UKG Pro without bypassing IT governance.

Instead of setting up direct connections with personal credentials that IT can't monitor or revoke, each employee authenticates through Agent Handler and gets individual credentials tied to their identity.

IT also provisions access by role or group via SCIM. An HR manager, for example, gets UKG Pro access to manage employee records and org changes, BambooHR to track PTO and HR requests, and Google Sheets to report on headcount and workforce metrics; while a finance analyst gets UKG Pro access to pull compensation and payroll data, NetSuite to close books, and Expensify to reconcile expenses.

Every tool call an employee's AI makes to UKG Pro is also inspected against your DLP rules and logged to a searchable audit trail, giving security teams full visibility into what data was accessed and by whom.