---
title: "Connect Humi by Employment Hero to Claude: Track Time Off & Records"
slug: connect-humi-by-employment-hero-to-claude-track-time-off-records
date: 2026-10-01
author: Sidharth Verma
categories: ["AI & Agents"]
excerpt: "Learn how to build a secure MCP server to connect Humi by Employment Hero to Claude. Automate time-off tracking, HR records, and payroll preparation workflows."
tldr: "A step-by-step engineering guide to securely connecting Humi by Employment Hero to Claude using a managed MCP server. Covers handling JSON:API complexities, routing time-off approvals, and securely tracking employee hours via natural language."
canonical: https://truto.one/blog/connect-humi-by-employment-hero-to-claude-track-time-off-records/
---

# Connect Humi by Employment Hero to Claude: Track Time Off & Records

**Humi by Employment Hero in Claude, in about a minute.** The best way to connect Humi by Employment Hero to Claude is Elaichi: connect Humi by Employment Hero to Elaichi once, then add Elaichi to Claude as a connector. Two steps, about a minute, with a 14-day free trial and no credit card required.

1. **Start your free trial.** Create your Elaichi account. 14 days free, no credit card required.
2. **Connect Humi by Employment Hero.** Connect Humi by Employment Hero once in Elaichi. Claude never gets more access than you have.
3. **Add Elaichi to Claude.** In Claude, open Customize, then Connectors, press Add and paste https://api.elaichi.ai/mcp. Sign in and approve.

[Start free on Elaichi, 14 days, no credit card required](https://app.elaichi.ai/signup?utm_source=truto.one&utm_medium=referral&utm_campaign=launchpad&utm_content=post_markdown&utm_term=humi) · [Humi by Employment Hero on Elaichi](https://elaichi.ai/connectors/humi/?utm_source=truto.one&utm_medium=referral&utm_campaign=launchpad&utm_content=post_markdown&utm_term=humi)

*Building Humi by Employment Hero into your own product? The guide below is for you.*

---

If you need to connect Humi by Employment Hero to Claude to audit time-off requests, retrieve employee directory information, or sync payroll data, you need a [Model Context Protocol (MCP) server](https://truto.one/what-is-mcp-and-mcp-servers-and-how-do-they-work/). This server acts as the translation layer between Claude's function-calling capabilities and Humi's REST architecture. You can either build and host this translation layer yourself, or use a [managed integration platform like Truto](https://truto.one/managed-mcp-for-claude-full-saas-api-access-without-security-headaches/) to dynamically generate a secure, authenticated MCP server URL. 

If your team uses ChatGPT, check out our guide on [connecting Humi by Employment Hero to ChatGPT](https://truto.one/connect-humi-by-employment-hero-to-chatgpt-manage-payroll-staff/) or explore our broader architectural overview on [connecting Humi by Employment Hero to AI Agents](https://truto.one/connect-humi-by-employment-hero-to-ai-agents-sync-hr-work-logs/).

Giving a Large Language Model (LLM) read and write access to a core Human Resources Information System (HRIS) is a significant engineering challenge. You must handle complex payload schemas, enforce strict data access boundaries, and translate human requests into highly specific API operations. Every time the underlying API deprecates a field or introduces a breaking change, 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 Humi by Employment Hero, connect it natively to Claude, and execute complex HR workflows using natural language.

> Want to give your AI agents secure, authenticated access to Humi by Employment Hero and 100+ other SaaS APIs? Let's talk about [managed MCP architecture](https://truto.one/managed-mcp-for-claude-full-saas-api-access-without-security-headaches/).
>
> [Talk to us](https://truto.one/book-a-demo/)

## The Engineering Reality of the Humi by Employment Hero 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 the Humi Partners API requires careful attention to specific architectural patterns. You are not just pushing standard JSON; you are navigating specialized spec implementations and aggressive data safeguards.

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

**The JSON:API Specification Complexities**
Humi relies heavily on the JSON:API standard. This means resources are not returned as flat JSON objects. Instead, a response contains a top-level `data` array (or object), where each item has an `id`, a `type`, and an `attributes` object containing the actual fields. Furthermore, related data (like an employee's salary or custom fields) is not nested within the employee object. It is returned in a separate top-level `included` array. 

Standard LLMs struggle heavily with this structure. If you give an LLM raw JSON:API output, it often fails to properly correlate an ID in a relationship mapping to the actual data in the `included` array. A managed MCP server abstracts this complexity by flattening schemas or explicitly guiding the model on how to parse the `attributes` wrapper, ensuring Claude receives data it can actually reason about.

**Aggressive Pagination and Empty Error Bodies**
Humi enforces a strict maximum of 25 records per page for its endpoints. When syncing an entire company directory or a month of time-off requests, the LLM must reliably execute cursor-based pagination via `next_cursor`. If the agent makes a mistake - such as passing an invalid or revoked token - Humi's closed-beta endpoints often return a `401 Unauthorized` with a completely empty response body. An unoptimized MCP server will crash or return an opaque null error to the LLM. Truto's tools explicitly define the `limit` and `next_cursor` logic in the schema descriptions to prevent hallucinated pagination parameters.

**Dangerous Payload Defaults**
The Humi API has uniquely destructive payload defaults that must be safeguarded. When calling the endpoint to create an employee time-worked entry, the API accepts a boolean parameter called `reset`. Alarmingly, Humi defaults this to `true`. According to Humi's documentation, `true` will "destroy all previous time worked entries on open payrolls." If you expose this raw endpoint to an LLM without strict schema guidance, a vague prompt like "Log 8 hours for John" could accidentally wipe out the entire company's open payroll logs. A managed MCP tool definition explicitly warns the LLM to pass `reset=false` unless explicitly instructed otherwise.

## Creating the MCP Server

Truto [derives MCP tools dynamically](https://truto.one/auto-generated-mcp-tools-for-ai-agents-a-2026-architecture-guide/) from an integration's configured resources and documentation records. You can generate a self-contained, authenticated MCP server scoped entirely to a single Humi by Employment Hero tenant. 

There are two ways to provision this server: via the Truto user interface, or programmatically via the API.

### Method 1: Via the Truto UI

For IT administrators or platform engineers manually setting up connections:

1. Log into your Truto environment and navigate to the integrated account page for the connected Humi tenant.
2. Click the **MCP Servers** tab.
3. Click **Create MCP Server**.
4. Define the desired configuration. You can assign a human-readable name, restrict the server to only `read` methods, or filter by specific tags (e.g., only exposing `time-off` tools).
5. Click Save and copy the generated MCP server URL (e.g., `https://api.truto.one/mcp/a1b2c3d4e5f6...`).

### Method 2: Via the Truto API

For engineers embedding this capability into an application, you can generate MCP servers programmatically. 

Send an authenticated `POST` request to `/integrated-account/:id/mcp` with your desired filtering configuration. The Truto platform will validate that tools exist, generate a cryptographically hashed token, and return a ready-to-use URL.

```typescript
const response = await fetch('https://api.truto.one/integrated-account/<INTEGRATED_ACCOUNT_ID>/mcp', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <YOUR_TRUTO_API_TOKEN>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: "Humi Time-Off Auditor",
    config: {
      methods: ["read", "list"], // Only allow read-only operations
      tags: ["hris", "time-off"] // Filter to specific domains
    },
    expires_at: "2026-12-31T23:59:59Z" // Optional TTL for the server
  })
});

const data = await response.json();
console.log(data.url); // The resulting MCP server URL
```

## Connecting the MCP Server to Claude

Once you have your Truto MCP URL, connecting it to Claude requires zero additional authentication configuration on the client side - the URL contains the cryptographic token necessary to route the request to the correct tenant.

### Method A: Via the Claude UI

If you are using an Enterprise or Team Claude account with UI-based connector management (similar to ChatGPT's custom connectors):

1. Open your Claude Settings and navigate to **Integrations** (or Connectors).
2. Click **Add MCP Server** or **Add Custom Connector**.
3. Paste the Truto MCP server URL you generated in the previous step.
4. Click **Add**. Claude will perform an initialization handshake to discover the available Humi tools and immediately make them available in your workspace.

### Method B: Via Manual Configuration File (Claude Desktop)

If you are running the Claude Desktop application locally, you connect the server by editing your configuration JSON file. Truto provides an SSE (Server-Sent Events) transport utility to connect remote MCP URLs to local clients.

Locate your Claude Desktop config file:
- Mac: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

Update the `mcpServers` object with the `npx @modelcontextprotocol/server-sse` command, passing your Truto URL as the argument:

```json
{
  "mcpServers": {
    "humi-hris": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/<YOUR_SECURE_TOKEN>"
      ]
    }
  }
}
```

Restart Claude Desktop. The application will detect the configuration, connect to the Truto edge infrastructure, and populate the tool definitions dynamically.

## Hero Tools for Humi by Employment Hero

The following tools are the highest-leverage operations available for orchestrating Humi via Claude. 

### List All Employees

**Tool Name:** `list_all_humi_by_employment_hero_employees`

This tool retrieves the employee index for the connected Humi account. Because Humi uses the JSON:API spec, the results are wrapped in a resource object structure. This tool handles pagination natively, ordering by oldest `created_at` first, returning a maximum of 25 items per page. Note that deleted employees are never returned.

> "Fetch the directory of all active employees, including their legal names, departments, and employment types. If there are more than 25, paginate through until you have the full list."

### Get Single Employee by ID

**Tool Name:** `get_single_humi_by_employment_hero_employee_by_id`

When you need deep details about an individual, such as their manager (`reports_to_id`), salary data, or custom attributes, use this tool. You must provide the Humi employee UUID. The tool supports the `include` parameter, allowing the LLM to fetch nested relationship data in a single call.

> "Retrieve the full profile for employee ID 550e8400-e29b-41d4-a716-446655440000. Include their salary records and custom attributes in the response so I can audit their current compensation."

### List All Time Off Requests

**Tool Name:** `list_all_humi_by_employment_hero_time_off_requests`

This tool fetches company-wide approved time-off requests that overlap with a specific date range. Humi requires strict `date_range_start` and `date_range_end` parameters formatted as YYYY-MM-DD. A critical operational constraint: this endpoint *only* returns approved requests. Pending and denied requests are silently excluded.

> "Pull all approved time off requests across the company between 2026-07-01 and 2026-07-15 to help me plan resource allocation for the upcoming sprint."

### List Employee Time Off Requests

**Tool Name:** `list_all_humi_by_employment_hero_employee_time_off_requests`

Similar to the company-wide tool, but scoped to a single employee UUID. It returns the same JSON:API resource structure, tracking day and hour totals alongside exact status dates. 

> "Check the approved time off for employee ID 123e4567-e89b-12d3-a456-426614174000 for the entire month of August 2026."

### List Additional Incomes

**Tool Name:** `list_all_humi_by_employment_hero_additional_incomes`

Before logging time-worked entries, you must identify the company-specific IDs for income types (e.g., regular hours, holiday pay). While Humi returns a standard machine-readable list, the IDs mapped to these values are entirely specific to the tenant.

> "Fetch the list of additional income types for this company so we can find the exact ID required to log holiday pay."

### Create Employee Time Worked

**Tool Name:** `create_a_humi_by_employment_hero_employee_time_worked`

This is a highly consequential write operation. It records time worked for a single employee on Humi's open payrolls. The tool schema explicitly forces the agent to manage the `reset` boolean. Setting `reset=false` appends the record; setting `reset=true` destroys all previous entries. Humi processes the payload amounts asynchronously, returning a 202 Accepted.

> "Log 8 hours of standard time worked for employee ID 987fcdeb-51a2-43d7-90e2-1234567890ab for today's date. Ensure that reset is explicitly set to false so we do not overwrite existing payroll records."

For the complete tool inventory and granular JSON schema definitions, view the [Humi by Employment Hero integration page](https://truto.one/integrations/detail/humi).

## Workflows in Action

Once connected, Claude can orchestrate multi-step HR data retrieval and payroll auditing workflows without human intervention. Here are two concrete examples of persona-specific automation.

### Workflow 1: The HR Manager's Capacity Audit

An HR Manager or Resource Planner needs to determine who is out of the office during a critical project delivery window, and ensure the specific employees' managers are aware.

> "Find out who is taking approved time off between 2026-11-01 and 2026-11-15. For each person taking leave, fetch their full employee record to identify their manager's ID, and compile a list of managers who need coverage."

**Execution Steps:**
1. Claude calls `list_all_humi_by_employment_hero_time_off_requests` with `date_range_start="2026-11-01"` and `date_range_end="2026-11-15"`.
2. The server returns a JSON:API array of approved requests containing `employee_id` attributes.
3. Claude iterates through the unique employee IDs, calling `get_single_humi_by_employment_hero_employee_by_id` for each.
4. Claude extracts the `reports_to_id` from the resulting attributes, identifying the managers.
5. Claude formulates a final summary report detailing the employees on leave and cross-referencing their respective managers.

```mermaid
sequenceDiagram
    participant User
    participant Claude as Claude Desktop
    participant Truto as Truto MCP
    participant Humi as Humi API

    User->>Claude: "Who is on leave and who manages them?"
    Claude->>Truto: call list_all_humi_by_employment_hero_time_off_requests
    Truto->>Humi: GET /time-off-requests<br>?dateRange[start]=2026-11-01
    Humi-->>Truto: Returns time-off records
    Truto-->>Claude: JSON:API payload
    loop For each employee ID
        Claude->>Truto: call get_single_humi_by_employment_hero_employee_by_id
        Truto->>Humi: GET /employees/{id}
        Humi-->>Truto: Returns employee + reports_to_id
        Truto-->>Claude: JSON:API payload
    end
    Claude->>User: Renders final coverage report
```

### Workflow 2: The Payroll Administrator's Overtime Sync

A Payroll Administrator needs to quickly process an ad-hoc overtime request for a contractor before the payroll window closes, but does not know the internal company ID for the "overtime" category.

> "I need to log 4 hours of overtime for employee ID 11112222-3333-4444-5555-666677778888. First, find the correct additional income ID for overtime, then log the time securely without resetting their other hours."

**Execution Steps:**
1. Claude calls `list_all_humi_by_employment_hero_additional_incomes` to pull the tenant's specific payroll category IDs.
2. Claude parses the attributes, matching the string "overtime" to the corresponding UUID.
3. Claude calls `create_a_humi_by_employment_hero_employee_time_worked` using the employee ID and the discovered income ID. Crucially, following the schema instructions, Claude sets `reset: false`.
4. The MCP server translates this to a POST request to Humi, which returns a 202 Accepted.
5. Claude confirms to the user that the 4 hours have been appended successfully.

## Security and Access Control

Giving AI agents write access to payroll and employee data requires stringent security boundaries. Managed MCP servers offer several layers of operational protection:

*   **Method Filtering:** When generating the server, you can restrict the configuration to `methods: ["read"]`. This physically prevents the LLM from ever seeing or executing destructive tools like `create_a_humi_by_employment_hero_employee_time_worked`.
*   **Tag Filtering:** You can restrict the server to specific operational domains, such as `tags: ["directory"]`, ensuring the LLM cannot access sensitive payroll or salary data tools.
*   **Expiration Controls (`expires_at`):** You can attach a strict TTL (Time To Live) to the MCP server URL. When an expiration is set, the platform automatically revokes the credential at the exact timestamp, invalidating all future requests without manual intervention.
*   **Layered Authentication (`require_api_token_auth`):** For enterprise environments, you can configure the MCP server to require an active platform API token in addition to the cryptographically secure URL, ensuring that possession of the URL alone is insufficient to access Humi data.

## A Note on Rate Limits

Factual note on rate limits: Truto does not retry, throttle, or apply backoff on rate limit errors. When Humi by Employment Hero returns an HTTP 429 Too Many Requests error, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit information into standardized headers (`ratelimit-limit`, `ratelimit-remaining`, `ratelimit-reset`) per the IETF specification. The caller - whether that is your custom code or an AI agent framework - is strictly responsible for interpreting these headers and implementing the necessary retry and backoff logic.

## Final Thoughts on Agentic HR Workflows

Connecting Claude to Humi by Employment Hero transforms static employee directories and manual payroll preparation into highly conversational, autonomous workflows. By leveraging an MCP server architecture to translate Humi's strict JSON:API requirements and dangerous payload defaults into LLM-friendly schemas, engineering teams can safely deploy AI agents into HR environments. Rather than spending weeks building custom scripts to traverse cursors and untangle nested relationship objects, you can provision secure, curated access in minutes and let the model do the heavy lifting.