Connect Humaans to ChatGPT: Automate HR Operations and Records

If you need to connect Humaans to ChatGPT to automate complex human resources operations, manage employee records, and orchestrate time-off policies, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between ChatGPT's native tool calling capabilities and the Humaans REST API.

You can either spend weeks building and maintaining this custom infrastructure, or you can use a managed integration layer to dynamically generate a secure, authenticated MCP server URL in seconds.

If your team uses Claude, check out our guide on connecting Humaans to Claude or explore our broader architectural overview on connecting Humaans to AI Agents.

Giving a Large Language Model (LLM) read and write access to a modern HRIS like Humaans is a massive engineering challenge. HR data is highly relational, strictly permissioned, and inherently point-in-time dependent. Every time a developer adds a custom field or modifies an organizational hierarchy, your custom server code must be updated, redeployed, and tested.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Humaans, 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 Humaans 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 an HRIS API is exceptionally painful.

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

Point-in-Time Data and Effective Dates

Modern HR systems do not store data as flat records; they store state changes over time. When an LLM asks "What is Alice's current salary?" you cannot simply query the person object. Humaans fragments this data across resources like compensations and job_roles, each tied to specific effective_date values. Your MCP server must teach the LLM how to query the compensations list, filter by the person ID, and parse the historical timeline to find the active record. Without strict schema definitions, the LLM will hallucinate past salaries as current ones.

Highly Fragmented Relational Schemas

To perform a routine task - like granting an employee a promotion - an LLM needs to orchestrate multiple independent API calls. It must fetch the user via the people resource, create a new entry in job_roles, potentially update the org_unit_assignments, and append a new record to compensations. If your MCP server does not perfectly map the JSON schemas for each of these endpoints, the LLM will fail to pass the correct foreign keys (like the Humaans ID) between steps.

Access Control and Security Scopes

HR data is the most sensitive data in your organization. A custom MCP server must implement flawless routing to ensure the LLM only accesses authorized data. If a user asks ChatGPT to list all employees, the server must inherently respect the API token's underlying scope constraints. Building static MCP schemas for this means writing a schema parser that understands the Humaans authentication model and dynamically generates JSON-RPC tool definitions based on what the token is actually allowed to see.

Humaans to ChatGPT Quickstart Guide

If you just want the fastest path from a fresh Truto account to ChatGPT calling the Humaans API, follow these steps. Deeper architecture, security, and lifecycle details live in the sections below.

What you need:

• A Truto account with API access.
• A Humaans admin account to authorize the connection.
• A ChatGPT Pro, Plus, Business, Enterprise, or Education seat with Developer mode available.

Step 1: Connect Humaans as an Integrated Account

In the Truto dashboard, navigate to Integrated Accounts -> New Integrated Account, select Humaans, and complete the authentication flow. Truto securely manages the credential lifecycle behind the scenes, ensuring ChatGPT never encounters an expired token.

Step 2: Grab Your Integrated Account ID

You will need the unique identifier for this specific Humaans connection. You can copy it directly from the Truto UI on the account detail page, or retrieve it via the API:

curl https://api.truto.one/integrated-account \
  -H "Authorization: Bearer $TRUTO_API_TOKEN"

Step 3: Generate the Humaans MCP Server

Truto dynamically generates MCP tools based on the underlying integration's documentation and resource definitions. You can create the MCP server in two ways.

Method 1: Via the Truto UI (Recommended for fast setup)

1. Navigate to the integrated account page for your Humaans connection.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration (e.g., restrict to read methods only, or filter by specific tags like payroll).
5. Copy the generated MCP server URL.

Method 2: Via the API (For programmatic workflows) Execute a POST request to generate an MCP endpoint scoped explicitly to that account. You can filter by methods and tags to strictly constrain what ChatGPT can touch:

curl -X POST https://api.truto.one/integrated-account/$INTEGRATED_ACCOUNT_ID/mcp \
  -H "Authorization: Bearer $TRUTO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Humaans HR Ops for ChatGPT",
    "config": {
      "methods": ["read", "write"],
      "tags": ["people", "time_away", "roles"]
    }
  }'

The response contains a url field structured as https://api.truto.one/mcp/<token>. This single URL carries the cryptographic routing and authentication context - treat it like a sensitive secret.

Step 4: Register the Server in ChatGPT

Now, you must provide ChatGPT with the server URL so it can discover the available Humaans tools. There are two ways to do this.

Method A: Via the ChatGPT UI

1. Open ChatGPT and go to Settings -> Apps -> Advanced settings.
2. Enable Developer mode.
3. Under MCP servers / Custom connectors, click to add a new server.
4. Give it a name (e.g., "Humaans HR Ops").
5. Paste the Truto MCP URL into the Server URL field and save.

ChatGPT will immediately connect, perform the JSON-RPC handshake, and list the available Humaans tools.

Method B: Via Manual Config File (for headless or custom agent setups) If you are running a custom MCP client setup or orchestrating locally, you can use the standard Server-Sent Events (SSE) transport configuration:

{
  "mcpServers": {
    "humaans-hr": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "--url",
        "https://api.truto.one/mcp/<your_secure_token>"
      ]
    }
  }
}

Hero Tools for HR Operations

Truto automatically generates highly descriptive, AI-ready tool schemas from the Humaans API documentation. When the LLM calls a tool, Truto maps the flat JSON arguments into the correct query parameters and request bodies.

Here are some of the highest-leverage tools available for automating Humaans workflows.

list_all_humaans_people

This tool retrieves the central employee records. It supports Humaans query filters and $limit/$skip pagination, which Truto normalizes automatically. The LLM can use this to look up employee IDs required for subsequent operations.

"Find the Humaans ID for the employee with the email address jsmith@example.com. Ensure you return their exact internal ID string."

update_a_humaans_person_by_id

Updates an existing employee record. Because it relies on the PATCH method conceptually, only the supplied fields are changed. This is critical for updating personal details, emergency contacts, or custom metadata without overwriting the entire record.

"Update John Smith's profile (ID: 98765) to change his preferred working location to 'Remote - US'. Leave all other fields exactly as they are."

list_all_humaans_time_away

Fetches time away (leave) entries for a person, including the per-day breakdown and approval status. This tool is vital for answering employee questions about their remaining balances or verifying if someone is on PTO.

"Check the time away records for Sarah Jenkins for the month of November. Is she scheduled for any approved PTO?"

create_a_humaans_time_away

Submits a new time away entry. The LLM handles constructing the complex JSON body required by Humaans, ensuring start dates, end dates, and leave types are correctly formatted.

"Submit a sick leave request for Marcus Aurelius for tomorrow. Set the status to approved since he already cleared it with his manager."

list_all_humaans_job_roles

Retrieves a person's job role history over time. Since Humaans tracks changes via effective dates, this tool is required to see job titles, departmental alignments, and reporting lines.

"Pull the job role history for Emily Chen. Who is her current direct manager, and when did she assume her current title?"

list_all_humaans_compensations

Retrieves the compensation entries for a person. This handles the complex nested arrays of amounts, currencies, and pay periods associated with effective dates.

"Fetch the compensation history for David Kim. What is his current base salary, and when was his last pay increase?"

To view the complete inventory of available tools, including operations for bank accounts, org hierarchies, and performance cycles, visit the Humaans integration page.

Workflows in Action

Exposing individual endpoints to an LLM is useful, but the real power of MCP lies in multi-step orchestration. Because Truto manages the session and standardizes the schemas, ChatGPT can chain together API calls to execute complex HR operations autonomously.

sequenceDiagram
    participant User as ChatGPT User
    participant AI as ChatGPT (MCP Client)
    participant Truto as Truto MCP Router
    participant API as Humaans API

    User->>AI: "Process a role change for Jane Doe to Senior Engineer."
    AI->>Truto: Call list_all_humaans_people (query: Jane Doe)
    Truto->>API: GET /people?email=jane.doe@...
    API-->>Truto: Return Person ID: 12345
    Truto-->>AI: Tool Result (ID: 12345)
    
    AI->>Truto: Call create_a_humaans_job_role (body: ID, new_title)
    Truto->>API: POST /job-roles
    API-->>Truto: 201 Created
    Truto-->>AI: Tool Result (Success)
    
    AI-->>User: "Jane Doe's role has been updated to Senior Engineer."

Scenario 1: Automating Employee Offboarding

When an employee leaves, HR admins must perform several operations across different data silos.

"We are offboarding Michael Scott effective this Friday. Please find his profile, update his employment status to terminated, and pull a report of any pending time-away requests he has submitted for future dates so we can cancel them."

Execution Steps:

1. ChatGPT calls list_all_humaans_people searching for "Michael Scott" to retrieve his Humaans ID.
2. It calls update_a_humaans_person_by_id using the retrieved ID, modifying the employment status and setting the termination date to the upcoming Friday.
3. It calls list_all_humaans_time_away, filtering by his ID and dates greater than this Friday, to identify pending PTO.
4. ChatGPT summarizes the pending PTO entries and returns them to the user for cancellation confirmation.

Scenario 2: Processing Ad-Hoc Bonus Approvals

Payroll managers often need to apply ad-hoc bonuses and ensure the historical record reflects the exact date of approval.

"Log a $5,000 performance bonus for Stanley Hudson. Set the effective date to today and ensure it is marked under the 'bonus' compensation type."

Execution Steps:

1. ChatGPT calls list_all_humaans_people to resolve Stanley Hudson's Humaans ID.
2. It calls list_all_humaans_compensation_types to verify the exact internal ID for the "bonus" pay classification.
3. It calls create_a_humaans_compensation, passing the employee ID, the compensation type ID, the amount ($5000), and the current date as the effective_date.
4. ChatGPT confirms to the user that the financial record has been appended to the employee's timeline.

Security and Access Control

Providing an AI agent with write access to an HRIS requires strict governance. Truto's MCP server architecture allows you to heavily constrain the LLM's blast radius at the token level, ensuring the AI can only perform approved operations.

• Method Filtering: You can restrict a specific MCP server to read-only operations by passing "methods": ["read"] during creation. This ensures the LLM can query employee data but physically cannot execute create, update, or delete tools.
• Tag Filtering: Humaans endpoints are grouped by functional tags. If you only want the LLM to manage time off, you can pass "tags": ["time_away"]. All other tools (like payroll or performance reviews) will be completely hidden from the AI.
• Additional API Authentication: For enterprise environments, you can enable require_api_token_auth. This forces the MCP client to send a valid Truto API token in the Authorization header alongside the cryptographic URL, adding a second layer of identity verification.
• Ephemeral Servers: By setting an expires_at ISO datetime when generating the server, Truto will automatically destroy the token and its associated tools via distributed cleanup schedulers once the time elapses. This is perfect for granting temporary HR audit access.

Rate Limits and API Resiliency

When deploying AI agents against SaaS platforms, volume management is critical. LLMs can execute loops or fan-out requests that quickly consume API quotas.

Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Humaans API returns an HTTP 429 (Too Many Requests), Truto passes that error directly back to the caller. Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification.

Your MCP client or agent framework is entirely responsible for reading these headers and implementing appropriate retry and backoff logic. Do not assume the integration layer will absorb rate limit errors on your behalf.

Summary

Connecting Humaans to ChatGPT transforms a static HR system into an active, conversational partner. By leveraging Truto's dynamically generated MCP servers, engineering teams can bypass the nightmare of schema mapping, authentication refreshes, and point-to-point maintenance.

Whether you are building read-only HR chatbots to answer employee PTO questions, or sophisticated AI agents capable of executing full offboarding workflows, the MCP architecture ensures your data remains secure, strictly scoped, and perfectly synchronized with the underlying APIs.

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