How to connect a UKG Pro MCP to Cursor (4 steps)

Before you can write a sync, a parser, or a validation rule with UKG Pro, you need to see what UKG Pro actually returns, and that usually means leaving the editor for a service account, an OAuth token, and a scratch script or Postman collection.

To help your developers query UKG Pro data without leaving Cursor, we'll show you how to connect with Merge Agent Handler's UKG Pro MCP server.

How it works

Merge Agent Handler connects Cursor to the UKG Pro API through the Merge CLI.

You install the CLI, authenticate once, and run a single setup command from your project root.

That command writes a ## Merge CLI section to your project's .cursorrules file, which tells Cursor's agent when to call merge search-tools and merge execute-tool to reach UKG Pro.

Once connected, Merge manages UKG Pro's OAuth credentials on your behalf, including token refresh and rotation, so you never store a company-specific secret in your project.

Related: How to use the UKG Pro MCP in Claude Code

Prerequisites

Before getting started, you'll need the following:

• A Merge Agent Handler account
• Cursor installed
• pipx installed (run pipx --version to confirm, or install via pip install pipx)
• A UKG Pro account with API access enabled (requires a UKG Pro service account and API credentials from your UKG administrator)

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.

1. Install the Merge CLI

Add the Merge CLI to your environment with pipx: pipx install merge-api

Confirm the installation succeeded: merge --version

2. Log in to Merge

Connect the CLI to your Merge Agent Handler account: merge login

This links the CLI to your account so Merge can make authorized requests against UKG Pro on your behalf.

3. Connect the CLI to Cursor

Run the following from the root of the project where you want to use Merge tools:

merge setup cursor

This writes a ## Merge CLI section to .cursorrules so Cursor knows to use the CLI for third-party services. The command is idempotent, so it's safe to re-run if you need to reset.

Related: A guide to integrating a UKG Pro MCP with Codex

4. Authenticate UKG Pro

Open a Cursor chat in your project and try a prompt such as:

Fetch one employee record and show every field it returns, including pay group, employment status, and FLSA classification, so I can model the object correctly before writing the sync.

The first time you invoke a UKG Pro tool, a Magic Link will appear to complete connector authentication.

{{this-blog-only-cta}}

UKG Pro MCP FAQ

In case you have more questions on setting up and using the UKG Pro MCP in Cursor, we've addressed several more commonly-asked questions below.

What can you do once the UKG Pro MCP is connected to Cursor?

With UKG Pro connected, Cursor can:

• Inspect the employee object before writing a parser: fetch a real employee record to see every field UKG Pro returns, including pay group, employment status, and FLSA classification, so your types match the API instead of a guess

• Resolve enum and code values before writing validation: pull the valid pay group, employment status, or job code values so your validation and type definitions use UKG Pro's real values, not assumed ones

• Check the job history and lifecycle event shape before writing change logic: retrieve a real job history record to see how transfers, promotions, and compensation changes are structured with their effective dates, before you write the code that processes them

• Inspect the org and position structure before writing traversal code: fetch a position or reporting-relationship record to see how UKG Pro represents the hierarchy before you write a function that walks it

• Validate pagination on a real employee list: run a query that returns many employees to see how pagination tokens come back before you implement your pagination loop

• Check a benefits enrollment record before writing enrollment logic: retrieve a real enrollment to see how coverage tiers and elections are structured before you write the sync that reads them

Why use Merge Agent Handler vs. a self-hosted UKG Pro MCP server?

You can build your own MCP server against the UKG Pro API. For a single developer working against one company's UKG Pro instance, that's a workable starting point: generate a service account, request API credentials, and wire up the endpoints you need.

The friction shows up once more than one person needs it, or the credentials need to be shared responsibly.

UKG Pro's OAuth model is company-specific, so a self-hosted setup means storing and refreshing those credentials somewhere, and there's no built-in way to limit which fields or operations a given agent or teammate can reach. UKG Pro holds compensation history, benefits elections, and personal data, and a self-hosted server that authenticates once grants that same access to everyone and everything using it.

Merge Agent Handler centralizes UKG Pro authentication and adds a control layer on top.

You can scope which UKG Pro operations a given agent is allowed to call, so a tool built to inspect job structure for code generation doesn't also reach payroll or compensation endpoints, and every call is logged with the timestamp, tool name, and inputs.

Why connect UKG Pro to Cursor?

Developers writing UKG Pro integrations have to understand its data model before the code will work: effective-dated job history records, pay group and employment status codes, and a position-based org structure that doesn't map cleanly to a simple employee list.

That structure is documented, but reading about it isn't the same as seeing what a real API response contains.

With the UKG Pro MCP connected, Cursor can pull real UKG Pro data directly in the chat panel. You can fetch an employee record while writing the parser that will process it, check a job history entry while writing the logic that tracks changes, or confirm pay group values while writing validation.

The data your code depends on and the code itself live in the same session, which cuts the round-trip to a separate API client or test script.

Can I use Merge Agent Handler's UKG Pro MCP with my employees?

Yes, Agent Handler for Employees is built to help organizations provision, secure, and govern how employees connect AI tools like Cursor to systems like UKG Pro.

Common patterns include:

• Provisioning and access control via SCIM with identity providers like Okta and Microsoft Entra ID, so IT can manage which employees can read or query UKG Pro data by role or team

• DLP and policy enforcement on tool calls, so admins can block queries that would return compensation, benefits, or other sensitive workforce data before results reach the editor session

• User-level audit logging so security and IT teams can review which workforce records were accessed, by which employee identity, and when

Put together, employees can use the UKG Pro MCP to look up employee records, check job history, validate workforce data while building internal tools, and more, while IT keeps centralized control over which workforce data each identity can reach.