Connect TriNet to Claude: Manage Workforce Identity and Compensation

If your team needs to connect TriNet to Claude to automate employee onboarding, reconcile payroll discrepancies, or manage complex workforce identity lifecycles, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's function-calling capabilities and TriNet's REST API. 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 TriNet to ChatGPT or explore our broader architectural overview on connecting TriNet to AI Agents.

Giving a Large Language Model (LLM) read and write access to a Professional Employer Organization (PEO) platform like TriNet is a serious engineering challenge. You are dealing with highly sensitive PII, complex compensation structures, and compliance-heavy workflows. Every time you query an employee record, you must navigate TriNet's unique permission scopes and non-standard payload envelopes.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for TriNet, connect it natively to Claude Desktop or your custom Claude applications, and execute complex HR workflows using natural language.

The Engineering Reality of the TriNet 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 enterprise HR APIs is difficult. TriNet operates as a co-employer, meaning its data models reflect intense compliance, tax, and benefits logic that standard SaaS APIs simply do not have.

If you decide to build a custom TriNet MCP server, here are the specific integration challenges you will face:

The Generic Response Envelope Problem

Unlike APIs that publish strict, per-endpoint 200 OK schemas, TriNet wraps its responses in a generic envelope. The actual entity data is nested inside a generic data object, and TriNet does not publish the exact properties of this object on a per-endpoint basis in their public specifications.

When building an MCP server, you must translate the target API's schema into JSON Schema for the LLM to understand what fields it can read or write. Because TriNet's schemas are unverified and generic, LLMs are flying blind. A managed MCP server from Truto handles this by actively mapping the known response paths and instructing the LLM on exactly how to unwrap the payload, preventing the model from hallucinating field names that do not exist.

Invisible Pagination and Query Constraints

For most modern REST APIs, when you hit a list endpoint, you expect standard query parameters like limit, offset, or cursor. TriNet publishes virtually no query or paging parameters for any of its endpoints.

If an LLM attempts to fetch a list of employees for a 5,000-person organization, the API behavior regarding chunking or limits is entirely opaque. Your integration layer must be prepared to handle whatever payload is returned without relying on predictable pagination cursors, and you must explicitly prompt your agents to handle large, un-paginated array responses.

Dynamic Section Scopes

Perhaps the most dangerous quirk of the TriNet API is how it handles data visibility. The API relies on granular section scopes. For example, when fetching a list of employees, the fields returned depend entirely on the scopes granted to the credential:

• basic-read returns department splits, basic employment info, and names.
• hr-personal-read adds emergency contacts, home addresses, and work eligibility.
• hr-pay-read adds compensation data.
• hr-natid-read adds national identification numbers (SSNs).

If your token only has basic-read, the API will still return a 200 OK - but the payroll fields will silently be missing. If an AI agent attempts to audit payroll data using a token with insufficient scopes, it will assume the data is null or empty, rather than inaccessible. A robust MCP implementation must be aware of these scoping limitations and surface descriptive errors to the LLM when required fields are missing from the envelope.

Rate Limit Handling

When operating at scale, LLMs can rapidly trigger API rate limits. TriNet enforces quotas on API usage. Truto does not retry, throttle, or apply backoff on rate limit errors. When the TriNet API returns an HTTP 429 Too Many Requests, Truto passes that error directly to the caller. However, Truto normalizes the upstream rate limit information into standardized IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). Your MCP client or agent framework is entirely responsible for reading these headers and executing the appropriate retry or backoff logic.

How to Generate the TriNet MCP Server

Truto abstracts away TriNet's schema anomalies, envelope wrapping, and authentication lifecycle. Instead of writing custom TypeScript or Python to map these endpoints to MCP JSON-RPC messages, you can generate a complete MCP server instantly.

You can create this server either through the Truto UI or programmatically via the API.

Method 1: Generating via the Truto UI

For teams testing workflows or deploying internal agents, the UI is the fastest path:

1. Log in to your Truto dashboard and navigate to your connected TriNet Integrated Account.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Configure your server:
   • Name: e.g., "TriNet Payroll Auditor"
   • Allowed Methods: Select read to ensure the LLM cannot mutate HR records, or specific methods like list and get.
   • Require API Token Auth: Toggle this on if you want to require a Truto API token in addition to the standard URL token.
5. Click Create and copy the generated MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4e5f6...).

Method 2: Generating via the REST API

For platforms provisioning AI agents for their own customers, you can generate MCP servers programmatically. This allows you to spin up heavily scoped, short-lived servers dynamically.

Make a POST request to the /integrated-account/:id/mcp endpoint:

curl -X POST https://api.truto.one/integrated-account/YOUR_ACCOUNT_ID/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "TriNet Automated Onboarding",
    "config": {
      "methods": ["read", "create", "update"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The Truto API will validate that the TriNet integration has documentation records available to generate tools, hash the secure token, and return the ready-to-use URL:

{
  "id": "mcp_srv_98765",
  "name": "TriNet Automated Onboarding",
  "config": { "methods": ["read", "create", "update"] },
  "expires_at": "2026-12-31T23:59:59.000Z",
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67890"
}

How to Connect the MCP Server to Claude

Once you have the Truto MCP URL, connecting it to Claude requires zero additional code. You can connect it via the UI or by modifying Claude's local configuration.

Method A: Connecting via the Claude UI

If you are using the Claude Desktop application or a web interface that supports MCP connectors natively:

1. Open Claude and navigate to Settings -> Integrations -> Add MCP Server.
2. Enter a descriptive name (e.g., "TriNet HR Data").
3. Paste the Truto MCP URL into the connection field.
4. Click Add.

Claude will immediately perform the MCP initialization handshake, query the /tools/list capabilities, and populate the TriNet tools into its context window.

Method B: Manual Configuration via JSON File

For headless deployments, local agent frameworks, or specific versions of Claude Desktop, you must configure the MCP server using a JSON configuration file. Because Truto provides the MCP server over HTTPS using Server-Sent Events (SSE), you will use the official @modelcontextprotocol/server-sse transport bridge.

Edit your claude_desktop_config.json file (typically located in your application data directory):

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

Restart Claude Desktop. The application will execute the npx command, establish the SSE connection to Truto's proxy router, and dynamically load the TriNet tools based on the filtering criteria you defined during creation.

Core TriNet Tools for Claude

Truto dynamically translates TriNet's REST API into discrete, strictly typed MCP tools. Here are the hero tools your AI agents will rely on for workforce management.

Note: Because TriNet utilizes a flat input namespace and generic envelopes, the query and body schemas are flattened for the LLM. Truto's internal router parses the LLM's arguments and maps them to the correct HTTP locations.

list_all_tri_net_employees

Fetches a complete list of employees for the connected company. The fields returned in the generic envelope depend entirely on the section scopes (e.g., basic-read vs hr-pay-read) associated with the OAuth credential.

"Fetch all active employees from TriNet. Review the payload and list the names and department IDs. If you see payroll or compensation data, extract that as well. If the payload seems sparse, let me know that our token scopes might be restricted."

create_a_tri_net_employee

Initiates the onboarding process by creating a new employee record. TriNet does not publish a strict request schema for this endpoint, meaning the LLM must construct the JSON body based on your prompt instructions or internal HR templates.

"Use the create_a_tri_net_employee tool to add a new hire. The employee's name is Sarah Jenkins, title is Senior Solutions Architect, and start date is next Monday. Construct a standard HR profile payload for the request body."

list_all_tri_net_payruns

Retrieves historical and upcoming payruns for the company. Crucial for financial auditing and ensuring payroll processing deadlines are met.

"List all recent payruns in TriNet. Identify any payruns scheduled for the next 14 days and extract their unique IDs so we can audit the individual paychecks."

get_single_tri_net_paycheck_detail_by_id

Fetches highly sensitive, granular data regarding a specific employee's paycheck, including gross pay, net pay, deductions, and tax withholdings. Requires both the employee_id and the paycheck id.

"Retrieve the detailed paycheck information for employee ID 'emp-8849' for paycheck ID 'chk-9912'. Break down the total tax withholdings and list any specific retirement contributions deducted from this period."

list_all_tri_net_leave_plan_accruals

Queries an employee's time-off accrual balances. This is frequently used to reconcile leave balances between TriNet and external scheduling or project management systems.

"Check the leave plan accruals for employee ID 'emp-3310'. Tell me exactly how many hours of PTO they have accrued this year, and how many hours are currently available to use."

tri_net_employee_jobs_bulk_update

Executes a job reclassification. This PUT request updates the employee's title, department, or job code. Like employee creation, the request schema is unpublished, so the payload must be carefully constructed.

"Process a job reclassification for employee ID 'emp-7721' using the tri_net_employee_jobs_bulk_update tool. Change their title to 'Lead Engineer' and update their department ID to 'dept-eng-01'."

For a complete list of all supported endpoints and schema definitions, review the Truto TriNet integration page.

Workflows in Action

Exposing these tools to an LLM transforms static HR data into an interactive, agentic workforce management system. Here are two real-world workflows you can execute using Claude and Truto's TriNet MCP server.

Workflow 1: New Hire Provisioning and Scoping

When a new employee signs their offer letter, an agent can verify their baseline data, create the TriNet profile, and set up their emergency contacts.

"We just finalized the hire for Marcus Thorne as a Data Scientist. First, create his employee record in TriNet with a start date of the 15th. Once you have his new employee_id from the response, add an emergency contact for him: his spouse, Elena Thorne, phone 555-0199. Confirm when both steps are complete."

Execution Steps:

1. Claude calls create_a_tri_net_employee, formatting the required JSON body for Marcus's basic profile.
2. TriNet returns a 200 OK generic envelope containing the new employee_id.
3. Claude parses the response, extracts the ID, and immediately calls create_a_tri_net_emergency_contact using that ID and the provided spouse details.
4. Claude responds to the user confirming the successful sequential creation.

sequenceDiagram
    participant User
    participant Claude as Claude Desktop
    participant MCP as Truto MCP Server
    participant TriNet as TriNet API
    
    User->>Claude: "Create new hire Marcus Thorne and add emergency contact..."
    Claude->>MCP: Call create_a_tri_net_employee
    MCP->>TriNet: POST /v1/hire/{company_id}/employee
    TriNet-->>MCP: 200 OK (Generic Envelope + new employee_id)
    MCP-->>Claude: JSON Tool Result
    Claude->>MCP: Call create_a_tri_net_emergency_contact(employee_id)
    MCP->>TriNet: POST /v1/profile/{company}/.../emergency-contacts
    TriNet-->>MCP: 200 OK
    MCP-->>Claude: JSON Tool Result
    Claude-->>User: "Marcus Thorne successfully provisioned."

Workflow 2: Payroll and Leave Accrual Audit

Finance teams often need to reconcile payroll runs against actual employee leave balances to ensure PTO isn't being incorrectly paid out or accrued.

"I need to audit the latest payroll run. First, list all payruns to find the most recent completed run ID. Then, get a list of all active employees. For the first three employees on that list, pull their leave plan accruals and their paycheck details for the recent payrun. Summarize any discrepancies between their PTO taken on the paycheck and their available accrual balances."

Execution Steps:

1. Claude calls list_all_tri_net_payruns to identify the ID of the last processed payroll.
2. Claude calls list_all_tri_net_employees to get the roster. It handles the generic envelope and selects the first three employee IDs.
3. For each of the three employees, Claude executes two parallel or sequential calls: list_all_tri_net_leave_plan_accruals and get_single_tri_net_paycheck_detail_by_id.
4. Claude aggregates the complex JSON responses, does the math comparing the paycheck PTO deductions against the accrual balances, and generates a human-readable audit summary.

Security and Access Control

Giving an LLM access to HR and payroll systems requires strict security guardrails. Truto's MCP servers are designed with Zero Trust principles built in at the token level:

• Method Filtering: Configure the MCP token to only allow read operations. If an agent attempts to hallucinate a create or update call, Truto rejects it before it ever reaches TriNet.
• Tag Filtering: Limit the server to specific operational domains. For example, you can create a server that only exposes resources tagged with timeoff, entirely blinding the LLM to payroll endpoints.
• Dual Authentication (require_api_token_auth): For maximum security, toggle this setting on. The client must provide a valid Truto API Bearer token in addition to the cryptographically hashed MCP server URL to establish a connection.
• Automatic Expiration (expires_at): Assign a strict TTL (Time to Live) to the MCP server. Truto uses Cloudflare KV and Durable Objects to guarantee the server is destroyed the second it expires, preventing stale credentials from lingering in agent memory.

Final Thoughts on Managed Integration Architecture

Integrating TriNet is not a matter of simply passing bearer tokens. You must orchestrate undocumented schemas, handle generic payload envelopes, navigate complex data scopes, and build resilient architectures around unforgiving rate limits.

Building a custom MCP server means taking on the maintenance burden of every undocumented TriNet API quirk. By utilizing Truto's dynamic, documentation-driven MCP server generation, your engineering team offloads the infrastructure, authentication, and schema translation overhead entirely. Your agents get immediate, strictly typed access to TriNet, allowing your team to focus on building advanced workforce intelligence workflows instead of debugging API envelopes.