Connect HR WORKS to Claude: Manage Hiring, Onboarding & Attendance

If your team needs to connect HR WORKS to Claude to automate absence management, orchestrate applicant onboarding, or audit time-tracking data, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's JSON-RPC tool calls and HR WORKS's REST API. You can either build and maintain this polling and routing infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL.

If your team uses ChatGPT, check out our guide on /connect-hr-works-to-chatgpt-automate-hr-admin-time-tracking/ or explore our broader architectural overview on /connect-hr-works-to-ai-agents-sync-payroll-expenses-hr-flows/.

Giving a Large Language Model (LLM) read and write access to a sprawling human resources platform like HR WORKS is a serious engineering challenge. You are dealing with asynchronous bulk write jobs, rigid pagination constraints, and complex identity resolution patterns. Every time HR WORKS deprecates a legacy identifier or updates an endpoint to v3, you have to update your server code, redeploy, and test the integration.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for HR WORKS, connect it natively to Claude, and execute complex HR workflows using natural language.

The Engineering Reality of the HR WORKS API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against a highly specialized B2B API like HR WORKS is painful. HR WORKS is built to handle enterprise-scale payroll, strict European labor compliance, and massive organizational hierarchies. Its API architecture reflects that complexity.

If you decide to build a custom HR WORKS MCP server, here are the specific integration challenges you will face:

The Asynchronous Job Pattern

Most write operations in HR WORKS (creating absences, updating personnel files, assigning cost centers) do not execute synchronously. Instead, endpoints like POST /v2/absences return a 202 Accepted with a jobId. To know if the write actually succeeded, you must poll a separate endpoint (e.g., GET /v2/absences/jobs/{jobId}). An LLM cannot handle this natively without explicitly defined tools for both the write action and the status check, plus strict prompting to enforce the polling loop. Truto handles this by exposing paired tools (e.g., create_a_hr_works_absence and get_single_hr_works_absence_job_by_id) so Claude can initiate the job and subsequently verify the result.

Non-Standard Error Wrapping

HR WORKS has specific permissions requirements for traversing organizational data. If an API key lacks permission to read a specific person's profile, standard API calls might fail outright with a 403. To prevent a single unauthorized sub-entity from failing an entire sync, Truto provides specific _or_error tools (like hr_works_persons_get_or_error). These endpoints catch HTTP errors from HR WORKS (like 403s or 5xxs) and return a 200 OK with a payload shaped like {"truto_error": {"status": 403}}. This allows the LLM to gracefully skip inaccessible records without crashing the entire conversation context.

Strict Rate Limits and Rigid Pagination

HR WORKS enforces strict rate limits to protect its infrastructure. Truto does not retry, throttle, or apply backoff on rate limit errors. When HR WORKS returns an HTTP 429, Truto passes that error directly to the caller, normalizing the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec. Claude (or your orchestration layer) is fully responsible for reading these headers and executing retry/backoff logic.

Furthermore, pagination in HR WORKS is highly rigid. Endpoints dictate a fixed page size (e.g., exactly 50 or 150 items), and any limit parameter passed by the client is actively ignored. Data is often returned as a single JSON object keyed by person identifiers rather than a standard JSON array. Your MCP server must properly map these nested object schemas so Claude understands the shape of the data it is parsing.

Generating the HR WORKS MCP Server

Truto dynamically generates MCP tools from the HR WORKS integration's resource definitions and schema documentation. Tools are not cached or pre-built; they are derived in real-time.

You can generate an MCP server for HR WORKS using either the Truto UI or the Truto REST API.

Method 1: Via the Truto UI

For teams who want a zero-code setup, you can generate the MCP URL directly from the dashboard.

1. Navigate to the Integrated Accounts page in your Truto dashboard.
2. Select your connected HR WORKS account.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration (e.g., filter by read or write methods, apply tool tags, or set an expiration date).
6. Copy the generated MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4e5f6...).

Method 2: Via the Truto API

For platform engineers building multi-tenant AI agents, you can programmatically provision MCP servers for your users via the Truto REST API. This is the standard approach for embedded SaaS architectures.

Make a POST request to the /integrated-account/:id/mcp endpoint:

curl -X POST https://api.truto.one/integrated-account/<HR_WORKS_ACCOUNT_ID>/mcp \
  -H "Authorization: Bearer <TRUTO_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Claude HR WORKS MCP",
    "config": {
      "methods": ["read", "write", "custom"]
    },
    "expires_at": null
  }'

The API securely hashes the token, stores it in Cloudflare KV, and returns the endpoint URL:

{
  "id": "mcp_8f7e6d5c",
  "name": "Claude HR WORKS MCP",
  "config": { "methods": ["read", "write", "custom"] },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67890"
}

Connecting the MCP Server to Claude

Once you have your Truto MCP URL, you need to register it with Claude. This connects Claude's reasoning engine directly to the Truto-hosted JSON-RPC routing layer.

Method A: Via the Claude UI

If you are using the consumer versions of Claude or ChatGPT that support custom connectors, you can add the URL directly via the interface.

1. In Claude, navigate to Settings -> Integrations -> Add MCP Server. (Note: If testing via ChatGPT's developer mode, navigate to Settings -> Connectors -> Add).
2. Enter a recognizable name (e.g., "HR WORKS by Truto").
3. Paste the Truto MCP URL (https://api.truto.one/mcp/...).
4. Click Add or Save.

Claude will immediately call the tools/list JSON-RPC method, discover the HR WORKS endpoints, and make them available in your chat session.

Method B: Via Manual Config File (Claude Desktop)

For developers building local agentic workflows with Claude Desktop, you must configure the MCP server using Server-Sent Events (SSE) in your claude_desktop_config.json file. Truto provides an open-source SSE proxy to handle the transport.

Edit your configuration file (typically located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "hr-works-truto": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/a1b2c3d4e5f67890"
      ]
    }
  }
}

Restart Claude Desktop. The application will initialize the SSE connection and map the HR WORKS schema to Claude's internal tool registry.

HR WORKS Hero Tools

Truto automatically exposes HR WORKS endpoints as standardized MCP tools. The query parameters and body schemas are flattened into a single JSON Schema object for Claude to parse. Here are 7 high-leverage hero tools for automating HR operations.

list_all_hr_works_absences

Lists absences per person in a specified date range. This tool returns the type, dates, status, and half-day flags. Because HR WORKS ignores the limit parameter, this tool relies heavily on the next_cursor logic provided in the Truto response schema.

"Claude, list all approved absences for the next 30 days. Let me know if anyone from the engineering organization unit has overlapping time off."

create_a_hr_works_absence

Initiates a bulk creation of absences. You can submit up to 100 absences at once. This is an asynchronous operation - HR WORKS accepts the payload and returns a jobId.

"Claude, create a sick leave absence for personnel number 4092 starting today and ending tomorrow. Check the job status immediately after to ensure it was accepted."

get_single_hr_works_absence_job_by_id

Retrieves the status and result of an asynchronous absence write. The id required is the jobId returned by the create_a_hr_works_absence tool. The job remains pending until HR WORKS processes it.

"Check the status of absence job ID 88392. If it is finished, verify there were no write errors in the response."

list_all_hr_works_time_accounts

Retrieves monthly time accounts per person, including working hours, target hours, time credits, and carry-overs. This is critical for auditing payroll and ensuring compliance with European time-tracking mandates.

"Pull the time account balances for the previous month. Identify any employees who have exceeded their target hours by more than 20 hours and flag them for review."

create_a_hr_works_person_working_time

Clocks a person in or out immediately. Unlike absences, this is a synchronous endpoint that returns the working time and any warnings directly. You can backdate the punch by up to 24 hours using ISO 8601 UTC timestamps.

"Clock in personnel number 1045 effective 15 minutes ago. Let me know if the system returns any warnings about overlapping shifts."

list_all_hr_works_applicants

Lists active applicants, including contact data, addresses, and status filters. It only returns applicants who have active job applications tied to their profile.

"Fetch all applicants currently in the 'Interview Phase' for the Senior Backend Engineer post. Summarize their earliest possible join dates."

create_a_hr_works_onboarding_document

Creates onboarding documents for new hires in bulk (up to 100 documents). This initiates the collection of personal, address, bank, and tax data before the candidate officially becomes an active person record in the system. This is an asynchronous write.

"Create an onboarding document for our new hire, Jane Doe, assigned to organization unit 44. Set her join date to next Monday and check the job ID to confirm it processed."

To view the full schema for all available endpoints - including expense reports, payroll files, and permanent establishments - view the HR WORKS integration page.

Workflows in Action

By chaining these MCP tools together, Claude can execute complex, multi-step HR automations completely autonomously.

Workflow 1: Logging Sick Leave and Auditing Coverage

When an employee calls in sick, the LLM must log the absence, verify the job completed, and check who else is out of the office to determine if coverage is needed.

"Log a sick leave for personnel number 802 for today and tomorrow. Once it is confirmed, check the absences for the rest of their organization unit to see if we are understaffed this week."

Execution steps:

1. Claude calls create_a_hr_works_sick_leaf with the personnel number and dates.
2. Truto returns the HTTP 202 response containing a jobId.
3. Claude enters a loop, calling get_single_hr_works_sick_leave_job_by_id until the job status changes from Pending to Finished.
4. Claude calls list_all_hr_works_absences filtered by the organization unit and current date range to cross-reference overlapping leaves.
5. Claude replies to the user confirming the sick leave was logged and provides a summary of the remaining staff availability.

sequenceDiagram
    participant Claude as Claude
    participant Truto as Truto MCP
    participant HRWorks as HR WORKS API

    Claude->>Truto: Call create_a_hr_works_sick_leaf
    Truto->>HRWorks: POST /v2/sick-leaves
    HRWorks-->>Truto: 202 Accepted (jobId: 9912)
    Truto-->>Claude: Result: jobId 9912

    Claude->>Truto: Call get_single_hr_works_sick_leave_job_by_id (9912)
    Truto->>HRWorks: GET /v2/sick-leaves/jobs/9912
    HRWorks-->>Truto: 200 OK (Status: Pending)
    Truto-->>Claude: Result: Pending

    note over Claude, HRWorks: Claude waits 5 seconds and retries

    Claude->>Truto: Call get_single_hr_works_sick_leave_job_by_id (9912)
    Truto->>HRWorks: GET /v2/sick-leaves/jobs/9912
    HRWorks-->>Truto: 200 OK (Status: Finished)
    Truto-->>Claude: Result: Finished (Success)
    
    Claude->>Truto: Call list_all_hr_works_absences (filtered)
    Truto->>HRWorks: GET /v2/absences
    HRWorks-->>Truto: 200 OK (Absence List)
    Truto-->>Claude: Result: Absence Map

Workflow 2: Onboarding an Applicant

When a candidate accepts an offer, the system needs to transition them from an applicant to a new hire by generating the required onboarding documentation.

"Find the applicant named John Smith. Once you find his UUID, generate an onboarding document for him assigning him to the Engineering unit starting on the 15th of next month."

Execution steps:

1. Claude calls list_all_hr_works_applicants to search the applicant pool and extract John Smith's UUID.
2. Claude calls create_a_hr_works_onboarding_document using the extracted data, mapping the private email, names, and join date.
3. Claude receives a jobId from the creation request.
4. Claude calls get_single_hr_works_onboarding_document_job_by_id to poll the status.
5. Upon completion, Claude informs the user that the onboarding packet is ready for the new hire.

Security and Access Control

Granting an LLM access to sensitive payroll, HR, and compliance data requires strict governance. Truto's MCP servers provide granular, token-level access controls to ensure your agents operate securely.

• Method Filtering: Enforce read-only access. By setting config.methods: ["read"] during server creation, Truto will mathematically strip all create, update, and delete operations from the tool list before Claude even sees them.
• Tag Filtering: Restrict access by domain. You can configure the MCP token to only expose tools tagged with recruiting, completely blocking the LLM from accessing payroll or time_tracking endpoints.
• Require API Token Auth: By default, possessing the MCP token URL grants access. By setting require_api_token_auth: true, the client must also pass a valid Truto API token via a Bearer header. This protects URLs that might be exposed in CI/CD logs or configuration files.
• Ephemeral Servers: Set an expires_at ISO datetime when generating the server. Truto's durable objects will automatically prune the KV token and database record when the time expires, making it ideal for temporary contractor access or limited-scope agent runs.

Summary

Connecting Claude to HR WORKS via a custom integration requires managing asynchronous polling logic, mapping complex identity hierarchies, and fighting rigid pagination constraints. By using Truto to generate a managed MCP server, you offload the infrastructure maintenance to an active API routing layer.

Truto automatically translates the HR WORKS API documentation into standardized JSON-RPC tools, enforces your security filters at the edge, and passes rate limit headers cleanly back to the client. This allows your engineering team to focus on building agentic workflows rather than writing boilerplate integration code.