Connect Humi by Employment Hero to ChatGPT: Manage Payroll & Staff

If you need to connect Humi by Employment Hero to ChatGPT to automate payroll logging, audit employee directories, or track time-off balances, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between ChatGPT's JSON-RPC tool calls and Humi's specific REST architecture.

If your team uses Claude, check out our guide on connecting Humi by Employment Hero to Claude 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) like Humi is a high-stakes engineering challenge. You must handle complex, nested JSON:API payload structures, navigate highly destructive default parameters on payroll endpoints, and map human concepts (like "Holiday Pay") to company-specific UUIDs before the LLM can write data.

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

Stop writing boilerplate API integration code. Let Truto generate secure, managed MCP servers for your AI agents in seconds. :::

The Engineering Reality of the Humi API

A custom MCP server is essentially a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, implementing it against Humi's highly specific API is exceptionally painful.

If you decide to build a custom MCP server for Humi by Employment Hero, you own the entire API lifecycle. Here are the specific integration challenges that break standard CRUD assumptions when working with this platform:

1. Strict JSON:API Compliance and the include Pattern

Humi adheres strictly to the JSON:API specification. Responses do not come back as simple flat objects. Instead, they are returned as documents containing data, jsonapi, and meta objects.

If an LLM asks "Who is this employee's manager and what is their salary?", standard endpoints will not return this data by default. Your MCP server must know to inject the include=salaries,custom_attributes query parameter. When it does, the relational data is not nested inside the employee object. It is returned in a top-level included array alongside a data.relationships mapping. You either have to teach the LLM how to parse JSON:API reference mappings, or write custom middleware in your MCP server to flatten this response before handing it to ChatGPT.

2. Destructive Defaults on Payroll Endpoints

When writing to the Humi Partners API, specifically the Employee Time Worked endpoint, Humi defaults the reset parameter to true.

According to Humi's documentation, passing true (or omitting the parameter entirely) "will destroy all previous time worked entries on open payrolls" for that employee. If you expose this raw endpoint to an LLM without strict schema validation or custom overrides, a simple prompt like "Log 8 hours for John today" will wipe out John's entire week of previously logged hours. Your MCP server must actively intercept this and default reset to false unless explicit replacement is requested.

3. Company-Specific IDs for Standard Types

When dealing with additional incomes (like Holiday Pay, Overtime, or Bonuses), Humi returns the same standard list of human-readable names for every company. However, the UUIDs for these income types are unique to each specific company instance.

An LLM cannot simply inject type: "holiday_pay" into a payroll POST request. It must first call the Additional Incomes Index, map the machine-readable string to the company-specific UUID, and then construct the payroll payload. This requires your MCP server to orchestrate multi-step tool calling effectively.

4. Opaque Errors on Closed Beta Endpoints

Humi labels several of its core Partner APIs as closed betas. If your authentication token is invalid, revoked, or if the specific Humi account has not been granted beta access to that specific endpoint, Humi does not return a helpful error message. It returns a 401 Unauthorized with a completely empty body. Your MCP server must be prepared to catch empty 401s and translate them into actionable errors for the LLM, otherwise the agent will infinitely retry a blank response.

Rate Limits and Upstream Behavior

When connecting AI agents to Humi, rate limiting is a primary concern. LLMs execute loops, retries, and rapid sequential requests that easily trip standard API quotas.

Factual note on rate limits: Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Humi API returns an HTTP 429 (Too Many Requests), Truto passes that error directly to the caller.

What Truto does do is normalize the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) following the IETF specification. The caller - whether that is your custom code or the ChatGPT framework - is entirely responsible for detecting the 429 and implementing appropriate retry and exponential backoff logic. Truto will not absorb these errors for you.

Generating a Humi MCP Server via Truto

Truto's MCP server feature turns any connected Humi instance into an MCP-compatible JSON-RPC endpoint. Rather than hand-coding tool definitions for Humi's JSON:API endpoints, Truto derives them dynamically from existing integration resource definitions and documentation schemas.

Each MCP server is scoped to a single integrated account. The server URL contains a cryptographic token that encodes the account, the exposed tools, and the expiration parameters.

You can generate this server via the Truto UI or programmatically via the API.

Method 1: Via the Truto UI

If you are setting this up manually for an internal ChatGPT Workspace:

1. Navigate to the Integrated Accounts page in the Truto dashboard.
2. Select your connected Humi by Employment Hero account.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration (e.g., restrict to read methods only, or filter by specific tags like payroll).
6. Copy the generated MCP server URL (it will look like https://api.truto.one/mcp/<token>).

Method 2: Via the Truto API

If you are provisioning AI capabilities for your own B2B SaaS customers, you will generate this URL programmatically.

Make a POST request to /integrated-account/:id/mcp. You can pass a configuration object to strictly limit what the LLM is allowed to do.

curl -X POST https://api.truto.one/integrated-account/<YOUR_INTEGRATED_ACCOUNT_ID>/mcp \
  -H "Authorization: Bearer $TRUTO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Humi Payroll Agent MCP",
    "config": {
      "methods": ["read", "create"],
      "tags": ["employees", "payroll", "time_off"]
    }
  }'

The API validates that the Humi integration has available tools matching your filters, generates a secure, hashed token stored at the edge, and returns the URL:

{
  "id": "abc-123",
  "name": "Humi Payroll Agent MCP",
  "config": { "methods": ["read", "create"] },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67890"
}

Treat this URL as a highly sensitive secret. Possession of the URL grants execution rights to the configured tools against that specific Humi account.

Connecting the MCP Server to ChatGPT

Once you have the Truto MCP URL, you must register it with ChatGPT.

Method A: Via the ChatGPT UI

For users on ChatGPT Pro, Plus, Business, Enterprise, or Education tiers:

1. Open ChatGPT and navigate to Settings -> Apps -> Advanced settings.
2. Toggle on Developer mode.
3. Under MCP servers / Custom connectors, click to add a new server.
4. Enter a name (e.g., "Humi HRIS").
5. Paste the Truto MCP URL into the Server URL field.
6. Click Save.

ChatGPT will immediately perform an MCP handshake, calling the initialize and tools/list JSON-RPC methods, and populate the available Humi tools into its context window.

Method B: Via Config File (Custom Agents / Local Dev)

If you are building a custom wrapper around OpenAI's API, or using a local framework that supports standard MCP configurations (like Cursor or Claude Desktop), you configure the server using a Server-Sent Events (SSE) client transport.

Add the following to your agent's MCP configuration JSON:

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

Humi by Employment Hero: Hero Tools

When the MCP server initializes, Truto dynamically generates descriptive snake_case tool names based on Humi's API definitions.

Here are the highest-leverage tools exposed to your LLM for HR and Payroll operations. (Note: Truto combines query and body parameters into a single flat input namespace for the LLM, handling the routing automatically).

list_all_humi_by_employment_hero_employees

Retrieves a paginated list of employees. Because Humi uses company-specific UUIDs for almost all write operations, this tool is the required first step for any agent workflow targeting a specific person.

Context note: This returns a standard JSON:API array. Deleted employees are filtered out by the upstream API. It supports pagination via limit and next_cursor.

"Get a list of all active employees in the engineering department and give me their names, employment types, and internal Humi IDs."

get_single_humi_by_employment_hero_employee_by_id

Retrieves deep relational data for a single employee using their UUID.

Context note: This is where the JSON:API include pattern is handled. The agent can pass include=salaries or include=custom_attributes to get relational data. The response will include a data.relationships mapping and a top-level included array containing the salary records (rate, frequency, effective dates).

"Look up the employee profile for ID 8f72a4b1 and include their current salary records and manager reporting structure."

list_all_humi_by_employment_hero_time_off_requests

Queries company-wide approved leave that overlaps with a specific date range.

Context note: This requires date_range_start and date_range_end formatted as YYYY-MM-DD. Pending and denied requests are silently excluded by Humi. This is critical for capacity planning workflows.

"Check the company time-off requests to see who is on approved leave between October 1st and October 15th."

list_all_humi_by_employment_hero_additional_incomes

Fetches the mapping of machine-readable income types to their company-specific UUIDs.

Context note: As mentioned in the Engineering Reality section, the LLM must call this tool before attempting to log custom payroll entries, so it can map strings like holiday_pay to the correct UUID for the create_a_humi_by_employment_hero_employee_time_worked tool.

"List the available additional income types for this company so we can find the exact ID for overtime pay."

create_a_humi_by_employment_hero_employee_time_worked

Records time worked or additional income on Humi's open payrolls.

Context note: DANGER. As documented by Humi, this endpoint defaults to destroying all previous entries if not handled correctly. Instruct your agent to always pass reset: false unless a complete replacement is intended.

"Log 4 hours of overtime for employee ID 8f72a4b1 using the overtime income ID. Ensure you set reset to false so we don't delete their standard hours for the week."

To view the complete schema definitions and the full inventory of available Humi tools (including webhooks and document management), visit the Humi by Employment Hero integration page.

Workflows in Action

With the MCP server connected to ChatGPT, complex HR scenarios that used to require custom scripts can now be executed conversationally. Here is how the LLM orchestrates multi-step workflows across the Humi API.

Scenario 1: Auditing Salary and Reporting Structures

HR teams frequently need to audit reporting lines and compensation bands.

"Find the employee record for Sarah Jenkins. Tell me who she reports to, and list out her active salary history."

Execution Steps:

1. ChatGPT calls list_all_humi_by_employment_hero_employees to search the directory and locate the UUID for "Sarah Jenkins".
2. ChatGPT calls get_single_humi_by_employment_hero_employee_by_id, passing Sarah's UUID and the parameter include=salaries.
3. ChatGPT parses the JSON:API response. It reads reports_to_id from the main attributes, cross-references it with the directory, and parses the included array to extract the salary rate, frequency, and effective dates.

Result: The user receives a clean, conversational summary of Sarah's reporting line and her complete compensation history without ever logging into the HRIS.

Scenario 2: Safe Payroll Data Entry

Logging custom income types requires precise data mapping and careful state management to avoid destroying existing payroll data.

"Log a $500 holiday bonus for Marcus Thorne. Make sure you don't overwrite his existing logged hours for this open payroll."

Execution Steps:

1. ChatGPT calls list_all_humi_by_employment_hero_employees to find the UUID for Marcus Thorne.
2. ChatGPT calls list_all_humi_by_employment_hero_additional_incomes to fetch the company's specific mapping table.
3. ChatGPT identifies the UUID corresponding to the holiday_pay or bonus attribute.
4. ChatGPT calls create_a_humi_by_employment_hero_employee_time_worked, passing Marcus's UUID, the bonus UUID as the rate ID, the amount, and critically, explicitly passing reset: false.

sequenceDiagram
    participant ChatGPT as ChatGPT
    participant MCP as Truto MCP Server
    participant Humi as Humi API
    
    ChatGPT->>MCP: Call list_incomes
    MCP->>Humi: GET /additional_incomes
    Humi-->>MCP: [{"id": "uuid-1", "name": "bonus"}]
    MCP-->>ChatGPT: Parsed JSON array
    
    ChatGPT->>MCP: Call create_time_worked<br>(reset: false)
    MCP->>Humi: POST /employee_time_worked
    Humi-->>MCP: 202 Accepted
    MCP-->>ChatGPT: Success confirmation

Result: The bonus is successfully appended to Marcus's open payroll without triggering Humi's destructive default behavior.

Scenario 3: Sprint Capacity Planning

Engineering managers need to know resource availability before committing to sprint deliverables.

"Check our approved time off. Who is out of the office between November 1st and November 14th?"

Execution Steps:

1. ChatGPT formulates the date objects for the start and end of the period.
2. ChatGPT calls list_all_humi_by_employment_hero_time_off_requests, passing date_range_start and date_range_end.
3. If the response contains more than 25 records, ChatGPT observes the next_cursor value and loops the call, passing the dates and the cursor back unaltered.
4. ChatGPT maps the returned employee_id fields to human names (calling the employee list if it doesn't already have them in context) and calculates total overlapping days.

Result: The manager receives a bulleted list of team members on leave, specifying exact dates and total hours absent during the sprint window.

Security and Access Control

Giving an AI agent access to an HRIS requires strict governance. Truto provides multiple layers of security configured at the MCP token level:

• Method Filtering: You can restrict a server to safe operations. By passing methods: ["read"] during server creation, Truto will enforce at the generation level that no create, update, or delete tools are ever exposed to the LLM.
• Tag Filtering: You can group tools by functional area. By passing tags: ["time_off"], the LLM will only see tools related to leave management, blocking access to sensitive endpoints like payroll or salaries.
• Time-To-Live (expires_at): You can generate short-lived MCP servers by passing an ISO datetime. Truto schedules a durable cleanup alarm that automatically revokes and deletes the server credentials at the exact specified time.
• Secondary Auth (require_api_token_auth): By default, the MCP URL is a bearer token. If you enable this flag, the calling client (the agent framework) must also provide a valid Truto API token in the Authorization header, adding a second layer of identity verification.

Final Thoughts

Integrating AI with Humi by Employment Hero unlocks massive operational efficiency, but the specific mechanics of the Humi API - strict JSON:API compliance, destructive payroll defaults, and opaque beta errors - make direct LLM integration risky.

Using Truto's managed MCP servers, you can instantly translate Humi's API into a safe, normalized, and highly-filtered JSON-RPC interface that ChatGPT and Claude understand natively. You maintain complete control over what the AI can see and do, without maintaining a single line of integration infrastructure.

Stop wrestling with JSON:API parsing and destructive defaults. Let Truto generate secure MCP servers for your HR stack today. :::