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

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. 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 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 or explore our broader architectural overview on connecting Humi by Employment Hero to AI Agents.

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.

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 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.

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:

{
  "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.

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.

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.