UKG Pro WFM MCP Server

Self-sufficient reasoning, hydration, orchestration, and execution layer for the UKG Pro Workforce Management API ecosystem.

What This Is

This is not a thin OpenAPI wrapper.

This server is designed to behave like a UKG Pro WFM reasoning layer. It accepts natural language, determines what the user is really asking, resolves missing inputs, discovers the correct API path, hydrates partial objects, traverses references, validates completeness, scores confidence, and returns full operational answers.

Core Rule

Search and list endpoints are discovery only. They are not final truth.

If an API response contains IDs, references, partial objects, child references, parent references, profile references, or linked configuration, the server must hydrate those objects before answering.

Execution Model

Traditional API Flow	UKG Pro WFM MCP Flow
User request	Natural language request
Pick endpoint manually	Detect intent and entities
Call one API	Resolve missing inputs
Return raw result	Discover, hydrate, validate, and answer

Capabilities

Capability	Purpose
Natural language routing	Understands operational questions without requiring endpoint knowledge
Missing input resolution	Finds IDs, refs, dates, employees, groups, profiles, and related objects
Discovery-only enforcement	Prevents list/search responses from being treated as final truth
Universal hydration	Pulls full detail for every reachable partial object
Object graph traversal	Follows parent, child, profile, group, org, and setup references
Completeness validation	Calculates whether the answer is complete enough to return
Confidence scoring	Classifies answers as CERTAIN, HIGH, MEDIUM, LOW, or BLOCKED
Write safety	Requires hydration, dry-run, explicit confirmation, and re-read after writes
Audit logging	Records source chain, duration, confidence, and affected objects

Supported Domains

Domain	Coverage Intent
Attendance	Events, patterns, and attendance-related operational context
Common Resources	Shared objects, lookup values, Hyperfinds, and common references
Employee Self Service	Employee-facing objects and request flows
Forecasting	Forecast-related workforce planning data
Healthcare Productivity	Productivity and staffing context
HCM	HCM-connected workforce data
Leave	Leave cases, requests, balances, and related context
People	Person, employee, manager, job, and org details
Person Assignments	Assignments, roles, and workforce relationships
Platform	Tenant, metadata, and platform-level capabilities
Scheduling	Schedules, shifts, coverage, and schedule analysis
Scheduling Setup	Scheduling configuration and setup references
Timekeeping	Timekeeping objects and operational time data
Timekeeping Setup	Pay rules, work rules, pay codes, and setup metadata
Timekeeping Timecards	Timecards, punches, exceptions, totals, approvals
Timekeeping Bulk Operations	Controlled bulk workflows with guardrails
Universal Device Manager	Device and clock-related operational context
Webhook Events	Event subscriptions and event payload normalization

Hydration Behavior

Traditional API result:

{
  "id": 1234,
  "name": "Hillcrest South"
}

Server behavior:

Resolve object
→ Discover detail endpoint
→ Retrieve complete object
→ Detect references
→ Hydrate references
→ Traverse relationships
→ Validate completeness
→ Return final answer

This applies to every object type, not just Known Places.

Confidence Levels

Level	Meaning
CERTAIN	Unique immutable identifier, full hydration, no unresolved dependencies, no conflicts
HIGH	Strong candidate, full target detail, minor non-critical references unavailable
MEDIUM	Likely answer, but some relevant references remain unresolved
LOW	Ambiguous or incomplete
BLOCKED	Cannot proceed safely because required data, access, or endpoint is unavailable

Architecture

Layer	Responsibilities
Catalog	OpenAPI ingestion, endpoint normalization, classification, endpoint graph
Reasoning Engine	Intent detection, entity extraction, missing input resolution, candidate ranking
Hydration Engine	Response graph parsing, dependency traversal, object hydration, completeness validation
API Client	Authentication, retries, pagination, rate limits, request tracing
Tool Layer	MCP tool registration, workflow composition, write safety, final answer formatting

Execution Pipeline

Natural Language
→ Intent Detection
→ Entity Extraction
→ Missing Input Resolution
→ Discovery Endpoint
→ Candidate Ranking
→ Primary Endpoint
→ Response Graph Parsing
→ Hydration Engine
→ Completeness Validation
→ Confidence Scoring
→ Business Interpretation
→ Response Formatting
→ Audit Logging

Primary Tool

ukg_wfm_ask

Use this for natural language requests.

Examples:

Show me the complete employee profile for employee 12345 and hydrate all manager and organizational references.

Explain every exception on employee 12345's timecard for last week.

Investigate why employee 12345 failed geofence validation yesterday.

Compare scheduled versus actual worked hours for ICU employees this pay period.

Hydrate the Emergency Department employee group and identify all connected profiles and references.

Write Safety

Every write operation follows the same lifecycle:

Resolve Inputs
→ Hydrate Target
→ Hydrate Dependencies
→ Dry Run
→ Explicit Confirmation
→ Execute
→ Rehydrate
→ Return Before/After State

Write, delete, and bulk operations cannot execute from:

name-only matches
search results
partial objects
inferred identities
ambiguous references

Only fully hydrated targets are eligible for mutation.

Installation

Clone the repository:

git clone https://github.com/fvmuzik00/UKG_Pro_WFM_MCP_Server.git
cd UKG_Pro_WFM_MCP_Server

Install dependencies:

npm install

Configure environment:

cp .env.example .env

Required environment variables:

UKG_BASE_URL=
UKG_CLIENT_ID=
UKG_CLIENT_SECRET=
UKG_APP_KEY=
UKG_USERNAME=
UKG_PASSWORD=
UKG_AUTH_MODE=client_credentials

Start development server:

npm run dev

Build production:

npm run build

Run tests:

npm test

Scorecard

Generate endpoint intelligence and risk outputs:

npm run scorecard

Outputs:

docs/endpoint-scorecard.json
docs/tool-risk-matrix.json

Project Goals

This project exists to eliminate three common problems in workforce management integrations:

Partial answers
Manual endpoint selection
Missing relationship awareness

The server's responsibility is not merely to call APIs.

Its responsibility is to understand the request, discover what information is missing, retrieve that information, validate it, and return the most complete answer possible from the available system of record.

UKG Pro WFM MCP Server