---
name: iblai-connect-workday-hcm
description: "Read and write Workday HCM data through the Workday Web Services (SOAP), Workday REST APIs, Reports-as-a-Service (RaaS) and expose it to an ibl.ai agent as an MCP tool. Use when the user asks an agent to work with Workday HCM data, or to set up a Workday HCM MCP connection on ibl.ai."
metadata:
  kind: guide
---

# Workday HCM connector for AI agents

> A starting point maintained on ibl.ai at https://ibl.ai/developer/connectors/workday-hcm — not part of the iblai/vibe repository. Checked against Workday, Inc.'s documentation on October 20, 2026; test it against your own Workday HCM setup before you rely on it.

Workday HCM is a cloud system of record for workers. A tenant stores worker profiles, positions and organizations, compensation, absence and time off, benefits, recruiting, learning and payroll data.

## Auth & conventions

- **API:** Workday Web Services (SOAP), Workday REST APIs, Reports-as-a-Service (RaaS) (Mixed). SOAP Workday Web Services (v47.0) cover Human_Resources, Staffing, Compensation, Absence_Management, Recruiting, Payroll and more. REST APIs serve small, low-latency calls. RaaS exposes a custom report as an XML or JSON web service.
- **Base URL:** https://api.workday.com/{service}/{version}/{resource}
- **Access:** Issued by your administrator. Only Workday customers (and their partners) get credentials. A tenant admin creates an Integration System User or runs the Register API Client task, and grants domain security for the data needed.
- **Auth:** OAuth 2.0 (API client registered in the tenant); Integration System User (ISU). REST APIs use OAuth and Workday's configurable security model, acting as the signed-in user or an integration system. The Register API Client task supplies the client ID and token endpoint; scopes are functional areas.
- **Limits:** Workday advises REST APIs for small, user-initiated requests and not for bulk export or import; SOAP web services are favored for large scheduled transfers.
- Keep Workday HCM credentials in environment variables or the ibl.ai credential store. Never print a token in chat and never commit one to a file.
- Destructive or outward-facing calls are marked **Confirm with the user first** — do.

## Reads

- **Workers** — Worker profiles, positions and organizations via the Human_Resources and Staffing web services.
- **Compensation** — Pay plans and worker compensation via the Compensation web service.
- **Absence and time off** — Time-off balances and requests via the Absence_Management web service.
- **Custom reports (RaaS)** — Call a custom report's URL and get XML or JSON back.
- **Recruiting** — Job requisitions and candidates via the Recruiting web service.

## Writes

- **Worker data changes** — Human_Resources and Staffing operations that create or edit worker data; many start business processes. **Confirm with the user first.**
- **Time-off entries** — Absence_Management operations to enter or adjust time off.

## Expose it to an ibl.ai agent (MCP)

Workday, Inc. publishes an official MCP server, Workday Agent-Ready Tools (MCP) (https://www.workday.com/en-us/ai-platform/agent-tools-mcp.html). Register it below as-is, or host your own server that wraps the calls in this skill.

First install the ibl.ai platform skills and connect your organization (writes `IBLAI_ORG`, `IBLAI_USERNAME` and `IBLAI_API_KEY` to `.env`):

```bash
npx skills add iblai/vibe --all
# then, in your coding agent:
/iblai-api-login
```

Every call below sends `Authorization: Api-Token $IBLAI_API_KEY`.

1. **Register the server** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-servers/` with `name`, `url`, `transport` (`sse` | `websocket` | `streamable_http`) and `auth_type` (`none` | `token` | `oauth2`). Capture the returned `id`.
   - For an API key or service credential use `auth_type=token` with `auth_scope=platform` for one key across the organization, or scope it to a single agent for one key per agent.
2. **Create the connection** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-server-connections/` with `server`, `scope` (`platform` | `mentor` | `user`), `auth_type`, and either `credentials` + `authorization_scheme` or a `connected_service` id for OAuth. Credentials are masked on read; never send a masked value back.
3. **Enable it on the agent** — `GET https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mentors/{agent_id}/settings/`, add `mcp-tool` to `tool_slugs` and the server id to `mcp_servers`, then `PATCH` the full lists back. They are replaced, not merged.

Full reference: https://ibl.ai/developer/platform/mcp/mcp-connections and the `/iblai-api-agent-mcp` skill.

## Example prompts

- "How many vacation days does Maria Lopez have left this year?"
- "List open requisitions in Engineering with no candidates in review"
- "Pull headcount by cost center from our 'Headcount Monthly' custom report"
- "Who reports directly to the VP of Finance?"

## Guardrails

- Holds employee personal data: government IDs, compensation, payroll bank details, and benefits elections that can include health information. Treat as sensitive HR data under privacy law.
- Request the narrowest Workday HCM scopes or role the task needs, and prefer a read-only credential for agents that only answer questions.
- Return the fields the user asked for, not whole records; do not paste personal data into chat that the user did not request.
- Before any write, show the user exactly what will change and wait for a yes.
- Respect the documented limits above: page through results and back off on rate-limit responses instead of retrying in a loop.

## References

- Workday Web Services directory (SOAP): https://community.workday.com/sites/default/files/file-hosting/productionapi/index.html
- REST APIs in apps and integrations: https://developer.workday.com/documentation/GUID-6b063b57-9d85-474b-99b0-734d714652fd-enHYPHENus/RESTAPIsinAppsandIntegrations
- Agent-Ready Tools and MCP: https://www.workday.com/en-us/ai-platform/agent-tools-mcp.html
- Workday Agent-Ready Tools (MCP): https://www.workday.com/en-us/ai-platform/agent-tools-mcp.html
- This connector on ibl.ai: https://ibl.ai/developer/connectors/workday-hcm
- ibl.ai MCP server connections: https://ibl.ai/developer/platform/mcp/mcp-connections