Table of contents
How to connect a Workday MCP with Claude Code (5 steps)
.png)
Headcount by department, reporting hierarchies, job levels, compensation bands, start dates, termination records: all of it lives in Workday, and developers building HR automation, workforce analytics, or internal people tooling need to reference it constantly.
The problem is that Workday's API is complex to set up. It requires tenant-specific URLs, Integration System User (ISU) configuration, and a working knowledge of Workday's data model before you can retrieve a single employee record.
To help your developers query Workday employee data and org structure directly from the terminal with ease, we'll show you how to connect Workday with Merge Agent Handler's Workday MCP server.
How it works
Merge Agent Handler sits between Claude Code and the Workday API. You configure a Tool Pack and Registered User in Merge Agent Handler, which generates a unique MCP URL. Claude Code connects to that URL over HTTP and uses an API key (generated in Merge Agent Handler) for authentication.
Here's the connection config before you substitute your specific values:
Claude Code sends requests to that MCP URL, and Merge handles authentication and API calls to Workday on the backend. You don't manage tenant URLs, ISU credentials, or Workday's API versioning yourself. Merge handles all of it.
Prerequisites
Before getting started, you'll need the following:
- A Merge Agent Handler account
- Claude Code installed (run
claude --versionto confirm) - Workday admin access to generate integration credentials for your tenant
Related: A guide to integrating a Google Calendar MCP with Claude Code
1. Create a Tool Pack
Log into Merge Agent Handler and navigate to Tool Packs. Click Create Tool Pack and give it a name tied to your use case, like "HR Workforce Intelligent Agent."
Under connectors, select Workday and pick the tools to enable.
For read-heavy workflows—querying employee records, pulling org structure, or retrieving job and compensation data—enabling employee listing, worker retrieval, and organization lookup covers the core cases. Add write tools if your agent needs to update worker records or trigger workflow actions.
Save the Tool Pack. You'll return here to copy your MCP URL in step 4.
2. Add a Registered User
Inside your Tool Pack, create a Registered User. This is the identity context under which your agent operates: the Workday integration user it acts on behalf of when calling the API.
Give it a name that maps to your environment, like dev-local or your own name. Once created, Merge generates a unique MCP URL scoped to this user.
3. Authenticate Workday
From the Registered User detail page, click Add Connector and select Workday.
Merge will prompt you for your Workday tenant credentials: your tenant URL, Integration System User (ISU) username, and ISU password. These are the credentials your Workday admin generates specifically for API integrations, not standard user login credentials.
Once you submit the credentials, Merge validates the connection and stores them securely. You won't need to re-enter them unless the ISU credentials are rotated or revoked.
4. Gather your credentials
You need two things before configuring Claude Code:
1. MCP URL: found on the Tool Pack detail page under the Registered User you just created. It looks like this:
2. API key: found in Settings > API Keys in your Merge Agent Handler dashboard. Create one if you don't have one yet.
Keep both handy for the next step.
5. Configure Claude Code with Workday
Run the following command in your terminal, substituting your actual MCP URL and API key:
Verify the connection registered with the command claude mcp list. agent-handler should appear in the output with a connected status.
To confirm the connector is accessible, open a Claude Code session and run a command like "List all active employees in the Engineering department and show me the reporting structure under the VP of Engineering."
You should see an output that looks something like the following:
{{this-blog-only-cta}}
Workday MCP FAQ
In case you have more questions on setting up and using the Workday MCP in Claude Code, we've addressed several more commonly-asked questions below.
What can you do once the Workday MCP is connected to Claude Code?
With Workday connected, Claude Code can:
- Query employee records: retrieve active workers by department, location, job level, or manager without navigating Workday's UI or writing a custom report
- Pull org structure: surface reporting hierarchies and team composition for any part of the organization, useful for headcount analysis or onboarding automation
- Read job and position data: fetch job profiles, compensation grades, and position details to give agents the context they need for HR workflow logic
- Check employment status: look up start dates, termination dates, and worker status to drive downstream automation like access provisioning or offboarding
- List open positions: retrieve unfilled roles and their attributes, useful for recruiting agents that need to match candidates against open headcount
- Cross-reference people data: combine Workday employee records with data from other connected tools, like pulling a worker's Workday profile alongside their Linear or GitHub activity in a single session
Why use Merge Agent Handler vs. a self-hosted Workday MCP server?
You can build a self-hosted MCP server that calls Workday's API directly. For a single developer with an existing ISU and a well-understood Workday tenant, that's a viable starting point. You configure the connection, write tool schemas against the Workday objects you need, and wire it to Claude Code.
Workday's API is one of the more complex surfaces in enterprise software. The tenant-specific base URL, ISU credential model, versioned WSDL schemas for SOAP endpoints, and separate REST API surface for newer objects mean there's meaningful upfront work before you get to the first useful query. Field names in Workday rarely map cleanly to what you'd expect: what most systems call "department" Workday calls an "organization," and hierarchies are modeled differently depending on the organization type.
At team scale, the self-hosted path adds more friction. Each developer managing their own ISU credentials means multiple integration users to maintain in Workday, no central control over which objects agents are allowed to read or write, and no audit trail of what was queried. When ISU credentials are rotated (which Workday admins do periodically), every developer's local setup breaks at once.
Merge Agent Handler abstracts the Workday-specific complexity and adds a control layer on top.
Tool-level scoping means a read-only headcount agent never gets access to write tools. Each Registered User gets isolated credentials, so credential rotation or access revocation doesn't cascade. And every tool call is logged.
For teams building agents against production Workday data, that's a meaningfully different operational posture than a locally stored ISU password.
Why connect Workday to Claude Code?
Workday holds organizational truth that developers need constantly when building HR tooling: who reports to whom, which positions are open, what a worker's employment status is, how departments are structured.
Accessing that data today usually means a browser, a Workday custom report, or a CSV export. None of that integrates naturally into an active coding session.
With the Workday MCP connected, Claude Code can retrieve worker records, traverse org hierarchies, and surface employment data without a context switch. That matters most when the query is part of a larger workflow: checking whether a worker is still active before provisioning access, pulling org structure to seed an onboarding checklist, or validating headcount data before pushing a report downstream.
.png)
.avif)
