Connect Humand to Claude: Automate Shifts, Documents & Scheduling

If you need to connect Humand to Claude to automate HR operations, manage shift schedules, handle document uploads, or track employee time, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's JSON-RPC tool calls and Humand's REST APIs. You can either build and maintain 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 Humand to ChatGPT or explore our broader architectural overview on connecting Humand to AI Agents.

Giving a Large Language Model (LLM) read and write access to a sprawling employee experience and HR platform like Humand is a severe engineering challenge. You have to handle API authentication lifecycles, map massive JSON schemas to MCP tool definitions, and deal with Humand's domain-specific data constraints. Every time an endpoint is updated or a new feature is added, 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 Humand, connect it natively to Claude Desktop, and execute complex workflows using natural language.

The Engineering Reality of the Humand 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 specialized B2B APIs is painful. Humand is built to manage complex organizational structures, internal communications, and time tracking. Its API reflects that domain complexity.

If you decide to build a custom Humand MCP server from scratch, you own the entire integration lifecycle. Here are the specific challenges you will face with the Humand API:

Merge-by-Type Relationship Semantics Managing the organizational chart (who reports to whom) is notoriously tricky. Humand's user upsert endpoints (like the alternate POST endpoint) do not use simple flat fields for managers. Instead, relationships use merge-by-type semantics. If you send an array of BOSS entries, it updates or clears the org-chart bosses and reviewers. If you send only REVIEWER entries, existing bosses are untouched. An LLM cannot simply guess this state machine logic. A managed MCP server exposes tools like humand_users_upsert_alt with strict JSON schemas that explicitly guide the LLM on how to construct these relationship arrays.

Complex Temporal File Uploads Handling files in LLM workflows is inherently difficult because LLMs do not natively buffer binary streams. Humand requires a multi-step process for secure file management. To upload a document, you often need to generate a signed temporal URL (humand_files_generate_signed_url_temporal), parse the AWS S3 policy headers (x-amz-algorithm, x-amz-signature), execute the upload, and then register the file back into Humand. Mapping this orchestration logic into discrete, actionable MCP tools requires deep middleware handling.

Multi-Dimensional Shift and Time Tracking Payloads Endpoints like humand_shifts_bulk_create require heavily nested payloads. You aren't just assigning a shift to an employee; you are submitting an array of employee shift assignments, each containing per-day entries specifying exact time slots and template IDs. The LLM needs precise schema definitions injected into its context to understand the required hierarchy of employee_id -> dates -> shift_details. If the schema is even slightly ambiguous, the LLM will hallucinate payload structures and throw 400 Bad Request errors.

Rate Limits: The Transparent Pass-Through Model

When exposing APIs to autonomous agents, rate limits are a critical failure point. It is a common misconception that integration platforms magically absorb rate limit errors.

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

What Truto does do is normalize the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The caller is completely responsible for reading these headers and implementing their own retry and backoff logic. Do not assume the MCP server will queue or throttle your requests automatically.

Generating the Humand MCP Server

Truto's architecture uses dynamic, documentation-driven tool generation. Rather than hand-coding tool definitions, Truto derives them in real-time from the Humand integration's resource definitions and schemas.

Each MCP server is scoped to a single integrated account (a specific tenant's Humand instance) and authenticated via a cryptographically hashed token stored at the edge.

You can generate the MCP server URL in two ways: via the Truto UI or programmatically via the API.

Method 1: Via the Truto UI

For administrators and internal tooling, generating the server via the UI takes seconds:

1. Navigate to the Integrated Accounts page in your Truto dashboard.
2. Select your connected Humand 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 tool tags).
6. Copy the generated MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4e5f6...).

Method 2: Via the Truto API

For platforms provisioning AI agents for their own users, you can dynamically generate MCP servers via the REST API. The API validates the configuration, generates the token, stores the hashed value in edge KV storage, and returns the ready-to-use URL.

curl -X POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Humand Shift Automation Agent",
    "config": {
      "methods": ["read", "write"],
      "tags": ["hr", "scheduling"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The response contains the secure URL that your client will use to connect:

{
  "id": "mcp_srv_9x8y7z",
  "name": "Humand Shift Automation Agent",
  "config": { "methods": ["read", "write"], "tags": ["hr", "scheduling"] },
  "expires_at": "2026-12-31T23:59:59.000Z",
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67890"
}

Connecting the MCP Server to Claude

Once you have the Humand MCP server URL, you need to register it with your Claude environment. All communication happens over HTTP POST with JSON-RPC 2.0 messages.

Approach A: Via the Claude UI (or ChatGPT UI)

If you are using the web interfaces for Claude (Enterprise/Team) or ChatGPT, you can add the server directly via the UI settings:

1. In Claude: Navigate to Settings -> Integrations -> Add MCP Server.
2. Paste the Truto MCP URL.
3. Click Add. Claude will immediately execute the initialize and tools/list JSON-RPC handshake to discover the Humand tools.

(Note: For ChatGPT, navigate to Settings -> Apps -> Advanced settings -> Developer mode -> Custom connectors).

Approach B: Via the Claude Desktop Config File

For local development using Claude Desktop, you configure the connection using the claude_desktop_config.json file. Because Truto MCP servers operate over standard HTTP, you use the official @modelcontextprotocol/server-sse transport.

Modify your config file (located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):

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

Restart Claude Desktop. You will see the Humand tools available in the attachment menu, ready for invocation.

Hero Tools for Humand

When Claude connects to the Truto MCP server, it asks for the available tools. Truto dynamically generates these based on the Humand API documentation schemas.

Here are the most high-leverage tools available for Humand operations.

list_all_humand_users

Retrieves a paginated list of all employees and users in the Humand instance. This is the foundational tool Claude uses to map a natural language name to a Humand employeeInternalId.

"Get a list of all active users in Humand and find the employee internal ID for Sarah Connor."

humand_users_upsert_alt

Creates a new user or updates an existing one using merge-by-type relationship semantics. This is critical for onboarding workflows and updating the organizational chart.

"Update Sarah Connor's profile in Humand. Add John Smith as her direct BOSS in the relationship array, but do not overwrite her existing REVIEWER relationships."

humand_time_off_list_requests

Fetches a list of all time-off requests submitted by employees. This tool allows Claude to audit upcoming leave and cross-reference it against project schedules.

"Pull the list of all pending time-off requests in Humand for the next two weeks. Summarize who will be out of the office."

humand_shifts_get_planning

Retrieves the shift planning calendar, returning paginated day records containing scheduled shifts and time-slot information for all employees.

"Get the shift planning calendar for this week. Which employees are currently scheduled for the night shift on Friday?"

humand_time_tracking_clock_in

Clocks an employee in to start a new time-tracking entry. This is highly useful for Slack/Teams bots where employees can clock in using natural language.

"Clock me into Humand. Start a new time tracking entry for the 'Site Reliability' project."

create_a_humand_document

Uploads and attaches a document to a specific user's profile. This tool handles the schema requirements for document metadata (source, extension, folder ID).

"Upload this signed offer letter as a document in Humand and attach it to the profile for employee ID 8472."

To view the complete inventory of available Humand tools, required parameters, and JSON schemas, visit the Humand integration page.

Workflows in Action

Connecting Claude to Humand transforms raw API endpoints into autonomous HR and scheduling workflows. Because Truto flattens the query and body schemas into a single MCP input namespace, the LLM can easily reason about complex payloads.

Here is how real teams use this architecture in production.

Workflow 1: Automated Shift Resolution and Cover Planning

An operations manager needs to handle a last-minute sick leave and reassign shifts without causing coverage gaps.

"Marcus called in sick for his shifts tomorrow and Thursday. Check the shift planning calendar to see what shifts he was assigned, find available employees in his department, and bulk create new shift assignments to cover his hours."

Step-by-step execution:

1. Claude calls list_all_humand_users to find the internal IDs for Marcus and the rest of his department.
2. Claude calls humand_shifts_get_planning to retrieve the exact time slots Marcus was scheduled for over the next 48 hours.
3. Claude analyzes the planning data to identify employees in the same department who do not have overlapping shifts.
4. Claude calls humand_shifts_bulk_create passing the multi-day shift assignment array to assign the open time slots to the available team members.

Result: The manager receives a confirmation message detailing exactly which shifts were reassigned and to whom, with the Humand backend updated in real-time.

sequenceDiagram
    participant User as Operations Manager
    participant Claude as Claude Desktop
    participant Truto as Truto MCP Server
    participant Humand as Humand API

    User->>Claude: "Marcus is sick. Reassign his shifts."
    Claude->>Truto: Call: list_all_humand_users (Find Marcus)
    Truto->>Humand: GET /users
    Humand-->>Truto: Return User IDs
    Truto-->>Claude: JSON Result
    
    Claude->>Truto: Call: humand_shifts_get_planning
    Truto->>Humand: GET /shifts/planning
    Humand-->>Truto: Return Shift Data
    Truto-->>Claude: JSON Result
    
    Claude->>Truto: Call: humand_shifts_bulk_create (New Assignments)
    Truto->>Humand: POST /shifts/bulk
    Humand-->>Truto: 200 OK
    Truto-->>Claude: Success
    Claude-->>User: "Shifts successfully reassigned to available staff."

Workflow 2: Employee Onboarding and Org Chart Synchronization

An HR administrator needs to initialize a new hire in the system and set up their reporting structure.

"We just hired Elena Rodriguez as a Senior Engineer. Create her user profile in Humand, set her employee internal ID to 'ENG-402', and assign David Chen as her BOSS."

Step-by-step execution:

1. Claude calls list_all_humand_users to search for David Chen and retrieve his exact employeeInternalId.
2. Claude constructs the complex relationship array using the merge-by-type semantics required by the Humand API.
3. Claude calls humand_users_upsert_alt with Elena's details, passing David's ID inside the BOSS relationship object.
4. Claude calls create_a_humand_document if an onboarding checklist or contract needs to be attached to her newly created profile.

Result: Elena is fully provisioned in Humand with the correct reporting lines established, requiring zero manual data entry from the HR team.

Security and Access Control

Giving AI agents write access to a core HR system requires strict guardrails. You do not want a hallucinating model accidentally wiping out a time-off policy or deleting users. Truto provides several layers of access control for MCP servers:

• Method Filtering: When generating the server via the API or UI, you can pass config.methods: ["read"]. The tool generator will enforce this at runtime, ensuring operations like delete_a_humand_user_by_id simply do not exist in the LLM's context.
• Tag Filtering: You can group tools by integration tags (e.g., config.tags: ["shifts"]) to create hyper-scoped MCP servers that can only access scheduling endpoints, completely isolating them from core user data.
• Expiration (TTL): You can set an expires_at timestamp. Once reached, a Durable Object alarm triggers a cleanup routine that purges the token from the database and edge KV storage instantly.
• API Token Authentication: By default, the cryptographically secure MCP URL is sufficient to connect. For zero-trust environments, you can enable require_api_token_auth: true, forcing the client to pass a valid Truto API bearer token alongside the URL.

Moving Beyond Brittle Scripts

Building an MCP server for a complex system like Humand is not a weekend project. You are signing up to maintain schema mappings, handle OAuth tokens, parse multi-part form data for file uploads, and keep pace with upstream API deprecations.

By leveraging a managed infrastructure approach, you abstract away the API mechanics. Truto handles the protocol translation and the connection state, allowing your engineering team to focus entirely on prompt engineering, agent orchestration, and building workflows that actually move the needle for your business.