Connect HiBob to Claude: Track Time Off, Salaries & Data Reports

If you need to connect your HRIS data to Anthropic's models to analyze employee lifecycles, manage time-off requests, or audit payroll history, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's natural language tool calls and HiBob's REST API. You can either spend weeks building and maintaining this 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 connecting HiBob to ChatGPT or explore our broader architectural overview on connecting HiBob to AI Agents.

Giving a Large Language Model (LLM) read and write access to a sensitive platform like HiBob is a massive engineering challenge. You have to handle OAuth 2.0 token lifecycles, map deep nested JSON schemas to MCP tool definitions, and deal with strict HR data access models. Every time HiBob updates an endpoint or changes a required field, 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 HiBob, connect it natively to Claude Desktop, and execute complex HR and operational workflows using natural language.

The Engineering Reality of the HiBob 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 HiBob's API requires dealing with domain-specific complexity. You are not just integrating "an API" - you are integrating a highly customized Human Resources Information System with dynamic fields, complex relationship histories, and strict rate limits.

If you decide to build a custom MCP server for HiBob, you own the entire API lifecycle. Here are the specific challenges you will face:

Fragmented Historical Data Models HiBob does not return a monolithic employee object. Basic demographic data lives in the people endpoints. If you want to know an employee's job title history, you have to query the work_history endpoints. For salary changes, you query payroll_history. For status changes, you query lifecycle_history. If you just hand Claude raw HTTP access, the model will hallucinate endpoints trying to fetch this data at once. You must provide distinct, schema-validated tools for each domain so the agent knows to look up the employee_id first, and then sequentially fetch the historical records.

Dynamic Custom Tables and Field Metadata Every enterprise customizes HiBob. Companies use "Custom Tables" to track everything from IT equipment assignments to professional certifications. You cannot hardcode tool schemas for these tables because the structure varies entirely by tenant. To build a functional agent, you have to first fetch the metadata (list_all_hi_bob_custom_tables), parse the field IDs and types, and inject that context into the prompt so the LLM knows how to structure its subsequent query or write operations.

Strict API Quotas and Rate Limit Passthrough HiBob enforces strict rate limits on API requests, particularly on broad queries like listing all employees or dumping time-off reports. Truto does not automatically retry, throttle, or apply backoff on rate limit errors. When HiBob returns an HTTP 429 Too Many Requests error, Truto passes that error directly back to the caller. However, Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. Your MCP client or AI agent is responsible for reading these headers and implementing its own retry and exponential backoff logic.

Instead of building all this boilerplate from scratch, you can use Truto to derive tool schemas dynamically from documentation and expose them over a standardized JSON-RPC 2.0 endpoint.

How to Generate a HiBob MCP Server with Truto

Truto's MCP architecture turns any connected HiBob instance into a fully functioning tool server. The tool definitions are generated dynamically - deriving their names, descriptions, and JSON Schemas from the integration's underlying configuration and documentation records.

You can generate the MCP server URL using either the Truto UI or the Truto REST API.

Method 1: Via the Truto UI

For teams who prefer a visual setup, generating an MCP server takes about 30 seconds:

1. Log into your Truto dashboard and navigate to the integrated account page for your connected HiBob instance.
2. Click on the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration. You can assign a human-readable name, restrict allowed methods (e.g., read-only), filter tools by functional tags, and set an optional expiration date.
5. Click Save and copy the generated MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4...).

This URL contains a hashed cryptographic token that routes requests directly to that specific tenant's HiBob account.

Method 2: Via the Truto API

For platform engineers building multi-tenant AI products, you can dynamically provision MCP servers for your users via the API. This creates a secure token stored in Cloudflare KV for high-speed edge lookups.

Send a POST request to /integrated-account/:id/mcp with your desired configuration:

curl -X POST https://api.truto.one/integrated-account/ab12-cd34-ef56/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Claude Desktop HiBob Access",
    "config": {
      "methods": ["read", "custom"]
    }
  }'

The API responds with the complete server configuration, including the ready-to-use URL:

{
  "id": "mcp_789xyz",
  "name": "Claude Desktop HiBob Access",
  "config": {
    "methods": ["read", "custom"]
  },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6g7h8i9j0"
}

Connecting the MCP Server to Claude

Once you have your Truto MCP server URL, you must configure your Claude environment to point to it. The server uses Server-Sent Events (SSE) via the standard @modelcontextprotocol/server-sse transport wrapper, ensuring compatibility across environments.

Method A: Via the Claude UI (Desktop/Web)

If you are using Anthropic's native interfaces that support custom connectors, adding the server is trivial:

1. Copy the MCP server URL generated by Truto.
2. In Claude, navigate to Settings -> Integrations (or Connectors depending on your tier).
3. Click Add MCP Server or Add custom connector.
4. Paste the Truto URL and click Add.

Claude will immediately execute the initialize and tools/list JSON-RPC handshake, discovering all the available HiBob tools automatically.

(Note for teams using OpenAI: The process is similar in ChatGPT. Go to Settings -> Apps -> Advanced settings, enable Developer mode, and add a new custom connector using the same Truto URL).

Method B: Via Manual Config File

For developers running local agents or the standard Claude Desktop application, you can configure the connection manually by editing the claude_desktop_config.json file.

Because Truto exposes an HTTP endpoint, you use the official MCP SSE transport utility to bridge Claude's local execution to Truto's remote server.

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

Save the file and restart Claude Desktop. The application will spawn the SSE transport process, connect to Truto, and pull the HiBob tools into its context window.

Hero Tools for HiBob

Truto automatically maps HiBob's API endpoints into snake_case tools complete with descriptions, query parameters, and body schemas. While the full integration supports dozens of endpoints, here are the highest-leverage tools for agentic workflows.

list_all_hi_bob_people

Retrieves a filtered list of employee records from the directory. This is typically the starting point for any agentic workflow, allowing Claude to resolve a human name or department into specific internal employee_id values required for subsequent tool calls.

"Find the employee ID for Sarah Connor in the Engineering department. Return her start date and direct manager."

list_all_hi_bob_time_off_requests

Fetches time-off requests across the organization or for a specific employee within a defined date range. Claude can use this to audit team availability, track pending approvals, or cross-reference planned PTO against project schedules.

"Get all time-off requests for the marketing team between June 1st and June 30th. Group the results by approved, pending, and rejected status."

list_all_hi_bob_payroll_history

Retrieves the historical salary entries from the payroll table for a specific employee. Because compensation changes over time, this tool returns an array of records denoting base salary, currency, pay frequency, and the effective date of each change.

"Fetch the payroll history for employee ID 12345. Calculate the total percentage increase in their base salary since their original hire date."

list_all_hi_bob_reports

Retrieves metadata for all custom and out-of-the-box company reports configured in HiBob. This allows the AI agent to discover which reports exist, who created them, and their specific internal folder IDs before attempting to trigger a download.

"List all active company reports in HiBob that contain the word 'Turnover' in the description or title."

get_single_hi_bob_task_by_id

Fetches the details of a specific onboarding, offboarding, or transition task assigned to an employee. Claude can use this to audit overdue items, verify completion dates, or check who requested the specific workflow step.

"Check the status of task ID 98765. If it is marked as incomplete, tell me who the task owner is and the original due date."

list_all_hi_bob_custom_tables

Fetches the schema and metadata for the custom tables configured in the specific HiBob tenant. This is crucial for dynamic discovery, allowing Claude to understand what custom fields exist (like "Company Assets" or "Certifications") and what data types they require before attempting to read or write entries.

"Fetch the custom table schemas for this HiBob account. Identify which table is used for tracking IT equipment and list its mandatory column names."

To view the complete inventory of available HiBob operations and their underlying JSON schemas, view the HiBob integration page.

Workflows in Action

Once connected, Claude can orchestrate multi-step data retrieval and analysis tasks that would normally require HR managers to export multiple CSV files and run VLOOKUPs.

Scenario 1: Auditing Team Compensation Changes

HR teams frequently need to audit the cadence of salary adjustments across specific departments to ensure parity.

"Find the payroll history for John Smith and list all salary increases over the last 3 years. Summarize the changes in a table."

Execution Steps:

1. Claude calls list_all_hi_bob_people with query parameters targeting the name "John Smith" to resolve the unique employee_id.
2. Claude takes that employee_id and calls list_all_hi_bob_payroll_history.
3. The tool returns an array of historical salary records. Claude parses the effectiveDate and baseSalary fields, computes the deltas between entries, and formats the output into a markdown table for the user.

Scenario 2: Analyzing Time-Off Liabilities

Finance and HR leaders need to track pending time-off balances at the end of the fiscal year to calculate payout liabilities or enforce use-it-or-lose-it policies.

"Check the current vacation time-off balances for everyone in the Sales department. Flag anyone who has more than 15 days accrued but has no pending time-off requests for December."

Execution Steps:

1. Claude calls list_all_hi_bob_people filtering by the department 'Sales' to get the roster of employee IDs.
2. For the resulting employees, Claude calls list_all_hi_bob_time_off_balances specifying the policy type 'vacation' and the current date to retrieve accurate accrued balances.
3. Claude iterates through the employees with >15 days accrued, calling list_all_hi_bob_time_off_requests with a date range covering December to verify if PTO is scheduled.
4. Claude returns a summarized list of the flagged employees to the user.

Security and Access Control

Exposing your HRIS to an LLM requires strict boundary setting. Truto's MCP servers are designed with multiple layers of access control, ensuring your AI agents operate securely.

• Method Filtering: You can restrict a server to specific operations via config.methods. Setting this to ["read"] ensures the server can only execute get and list operations, physically preventing the LLM from accidentally updating a salary or terminating an employee.
• Tag Filtering: You can scope the server by functional area using config.tags. For example, assigning a tag filter ensures the LLM can only access tools related to time-off and tasks, entirely omitting payroll and equity endpoints.
• Require API Token Authentication: For elevated security, setting require_api_token_auth: true adds a secondary middleware check. Possession of the MCP URL alone is no longer sufficient; the MCP client must also pass a valid Truto API token in the Authorization header to execute a tool.
• Ephemeral Servers: You can provision temporary access using the expires_at property. Cloudflare KV and a Durable Object alarm will automatically purge the server token at the specified ISO datetime, instantly revoking the LLM's access to the environment.

Connect HiBob to Your AI Workflows Today

Building a custom integration to map LLM tool calls to HiBob's API is a distraction from building your core product. Truto handles the heavy lifting - dynamically generating tools from documentation, parsing schemas, managing authentication, and normalizing pagination.

By leveraging Truto's managed MCP servers, you can connect Claude directly to HiBob in minutes, giving your agents secure, real-time access to directory structures, time-off requests, and custom HR data.