Connect Justworks to Claude: Automate Deductions & Personnel Data

If your HR or finance team needs to connect Justworks to Claude to automate payroll deductions, extract custom member fields, or audit time-off policies, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's tool calls and Justworks'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 Justworks to ChatGPT or explore our broader architectural overview on connecting Justworks to AI Agents.

Giving a Large Language Model (LLM) read and write access to a sprawling HRIS and payroll ecosystem like Justworks is a significant engineering challenge. You have to handle strict OAuth 2.0 token lifecycles, map massive JSON schemas to MCP tool definitions, and deal with Justworks's unique API constraints. Every time Justworks updates an endpoint, adds a new scope requirement, or deprecates a 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 Justworks, connect it natively to Claude Desktop, and execute complex payroll and personnel workflows using natural language.

The Engineering Reality of the Justworks 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, the reality of implementing it against Justworks's API is painful. Justworks manages sensitive financial, tax, and employment data, meaning its API is strictly governed by granular scopes, rigid data typing, and asynchronous reporting models.

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

Granular Scope Dependencies and Silent Omissions Justworks enforces highly granular permission scopes - such as member.detail:read, member.dob:read, member.sex:read, and member.pay:read. If an application requests a member record without holding the member.dob:read scope, the API does not throw a 403 Forbidden error. Instead, it silently omits the date_of_birth field from the response payload. An unmanaged LLM expecting this field will often hallucinate data when it encounters a missing key. A managed MCP server derives its JSON schemas directly from the active configuration, explicitly instructing the model about which fields are available based on the authenticated scopes.

Strict Integer Arithmetic for Payroll and Deductions The Justworks API rejects floating-point numbers. For fixed currency amounts, payloads must be formatted as integers representing cents (e.g., $45.00 must be submitted as 4500). For percentage-based calculations, Justworks requires an integer with a four-decimal shift (e.g., 3.7% must be submitted as 37000). If Claude sends a float, the API returns a 400 Bad Request. Your MCP layer must include precise schema descriptions that force the LLM to perform the correct integer math before dispatching the payload.

Asynchronous Reporting for Time-Off Balances Not all endpoints in Justworks execute synchronously. Querying time-off balances requires an asynchronous job pattern. You cannot simply send a GET request and receive a payload of balances. You must first issue a POST request to time_off_balance_reports, extract the report_id, and repeatedly poll the GET endpoint until the status field switches from pending to ready. Teaching an LLM to navigate this asynchronous polling pattern requires explicitly chained MCP tools.

Transparent Rate Limit Handling Justworks imposes rate limits to protect its infrastructure. It is critical to understand that Truto does not magically absorb, retry, or apply backoff to these rate limit errors. When Justworks 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 IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). Your MCP client, or the AI agent orchestrator driving Claude, is strictly responsible for implementing the retry and backoff logic.

Generating a Justworks MCP Server

Truto dynamically generates MCP servers for Justworks using your integration's existing documentation and resource configurations. This means tools are always up-to-date with your active API schemas. There are two ways to generate an MCP server for a connected Justworks account: via the Truto UI or via the API.

Method 1: Generating via the Truto UI

If you are configuring access for a local Claude Desktop instance or manually provisioning an environment, the UI is the fastest route:

1. Log into your Truto dashboard and navigate to the Integrated Accounts page.
2. Select the specific Justworks connection you want to expose to Claude.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration - you can restrict access to specific tags (e.g., payroll, personnel) or specific HTTP methods (e.g., read, write).
6. Copy the generated MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4...).

Method 2: Generating via the Truto API

For production workflows where you are dynamically provisioning AI agents for multiple tenants, you will generate MCP servers programmatically.

Make a POST request to /integrated-account/:id/mcp with your Truto API key:

const response = await fetch('https://api.truto.one/integrated-account/YOUR_ACCOUNT_ID/mcp', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TRUTO_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: "Justworks Payroll Agent",
    config: {
      methods: ["read", "write"], // Allow both querying and updating records
      tags: ["deductions", "members"] // Restrict to specific resource groups
    },
    expires_at: "2026-12-31T23:59:59Z" // Enforce an expiration date
  })
});
 
const data = await response.json();
console.log(data.url); 
// Output: https://api.truto.one/mcp/a1b2c3d4...

The resulting URL contains a cryptographically hashed token that securely authenticates requests and binds them to the specific Justworks tenant account.

Connecting the MCP Server to Claude

Once you have your Truto MCP URL, you need to register it with Claude so the model can discover and execute the Justworks tools.

Method A: Via the Claude UI

If you are using an Enterprise or Team Claude account with remote MCP connector support:

1. Open Claude and navigate to Settings.
2. Click on Integrations or Connectors.
3. Click Add MCP Server or Add custom connector.
4. Paste the Truto MCP URL you generated.
5. Click Add.

Claude will immediately ping the endpoint, perform an initialization handshake, and populate its context window with the available Justworks tools.

Method B: Via Manual Config File (Claude Desktop)

If you are developing locally using the Claude Desktop app, you will configure the server using a JSON file. Truto MCP servers operate over Server-Sent Events (SSE), meaning you will use the official @modelcontextprotocol/server-sse package to handle the transport layer.

Open your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the Justworks server block:

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

Restart Claude Desktop. The model will now have secure access to the Justworks environment.

Security and Access Control

Granting an LLM access to HRIS and payroll data demands strict guardrails. Truto's MCP architecture provides several layers of access control configured during server creation:

• Method Filtering (config.methods): Restrict the MCP server to specific HTTP verbs. You can enforce a read-only agent by passing ["read"] (allowing only GET and LIST), preventing Claude from accidentally mutating payroll records.
• Tag Filtering (config.tags): Limit the agent's context to specific business domains. By passing ["time_off"], you ensure the agent can audit time-off balances but has no visibility into the payrolls or paystubs resources.
• Dual-Layer Authentication (require_api_token_auth): By default, the cryptographically secure MCP URL acts as the authentication token. If you enable this flag, the calling client must also supply a valid Truto API token in the Authorization header, preventing leaked URLs from being abused.
• Automatic Expiration (expires_at): Bind the MCP server to a strict Time-To-Live (TTL). Once the ISO datetime is reached, Truto's durable alarms automatically destroy the KV entry and database record, instantly revoking the agent's access.

Hero Tools for Justworks

Truto automatically derives highly descriptive, snake_case tools from the Justworks API documentation. Because tools are dynamically generated based on active scopes, Claude only sees what it is authorized to touch.

Here are six high-leverage hero tools your AI agents can use to automate Justworks operations:

list_all_justworks_members

This tool retrieves the employee, contractor, and owner roster for the connected company. It supports cursor-based pagination and allows filtering by status (active or terminated) or exact update dates (updated_at_gte). Because of Justworks's scope-gating, Claude is explicitly informed via the tool schema that fields like date_of_birth and current_pay will only be returned if the respective scopes are authorized.

"Fetch a list of all active employees in the Engineering department. Make sure to retrieve their current job titles and manager IDs."

get_single_justworks_paystub_by_id

While the list_all_justworks_paystubs tool returns high-level summaries, this tool dives into the granular line items for a specific paystub ID. It returns earnings, employee_deductions, and employer_contributions. The LLM uses this tool to audit specific payroll discrepancies.

"Get the detailed paystub for ID paystub_889922. Break down the exact amounts allocated to employee deductions versus employer contributions."

list_all_justworks_deductions

This tool lists all active payroll deductions across the company. It can be filtered by member_id, deduction_type, or frequency. The tool schema instructs Claude on how to interpret the amount field based on the amount_type - treating fixed amounts as cents and percentages as four-decimal integers.

"List all active deductions for member ID member_4455. Flag any deductions that are classified as percentage-based rather than fixed-amount."

create_a_justworks_deduction

This tool allows Claude to execute bulk deduction creation in a single API call by passing an array of items. It requires precise integer math. If Claude needs to set up a 5% 401k deduction, the tool schema strictly guides it to submit 50000 as the amount.

"Set up a new monthly recurring deduction for member_4455 using deduction type code '401K_PRE'. The amount should be exactly 4.5% of their gross pay. Start the deduction on 2026-03-01."

list_all_justworks_time_off_requests

This tool queries historical and future time-off requests, requiring start_date and end_date parameters. It allows filtering by status (e.g., requested, approved, declined). Claude uses this to reconcile attendance records against active pay periods.

"Pull all approved time-off requests for the month of July 2026. Calculate the total number of hours taken across the organization."

update_a_justworks_member_by_id

This write-enabled tool allows Claude to update a member's organizational placement. It accepts sparse updates - meaning Claude only sends the fields that are changing, such as job_title, department_id, or manager_id. On success, it returns an empty 204 response.

"Update member_4455's profile. Change their job title to 'Senior Backend Engineer' and reassign their manager ID to member_1122."

For the complete inventory of available Justworks tools - including custom fields, bank accounts, business info, payroll fees, and subscription management - visit the Justworks integration page.

Workflows in Action

Providing Claude with MCP access to Justworks allows you to replace complex, multi-system manual tasks with natural language workflows. Here are two concrete examples of how Claude chains tools together to solve real-world operational problems.

Scenario 1: Auditing and Updating Benefit Deductions

When a company rolls out a new employer-matched retirement benefit, HR admins often need to audit existing employee deduction rates and bulk-update them to a new baseline. Instead of exporting CSVs and running manual VLOOKUPs, an admin can instruct Claude to handle the migration.

"Find all active employees currently enrolled in the '401K_PRE' deduction plan. If their current deduction percentage is less than 3%, update their deduction to exactly 3%. Ensure the update takes effect on the first of next month."

Step-by-step execution:

1. Claude calls list_all_justworks_members with status: "active" to retrieve the current roster of employees, capturing their member_ids.
2. Claude loops through the roster, calling list_all_justworks_deductions with the deduction_type filter set to 401K_PRE.
3. Claude inspects the results. Because the schema clearly defines percent math, it correctly identifies that an amount of 25000 represents 2.5%.
4. For all identified members beneath the threshold, Claude compiles a batch array and calls justworks_deductions_bulk_update, passing the target deduction_id, the new amount: 30000 (3%), and the requested start_date.

sequenceDiagram
    participant User as User
    participant Claude as Claude Desktop
    participant Truto as Truto MCP Server
    participant Justworks as Justworks API

    User->>Claude: "Find all active employees with < 3% 401k deductions and update them to 3%."
    Claude->>Truto: Call list_all_justworks_members (status: active)
    Truto->>Justworks: GET /members?status=active
    Justworks-->>Truto: Return member list
    Truto-->>Claude: JSON response
    
    Claude->>Truto: Call list_all_justworks_deductions (type: 401K_PRE)
    Truto->>Justworks: GET /deductions?deduction_type=401K_PRE
    Justworks-->>Truto: Return deductions
    Truto-->>Claude: JSON response
    
    Note over Claude: Analyzes amounts.<br>Converts 3% to 30000.<br>Compiles bulk update array.
    
    Claude->>Truto: Call justworks_deductions_bulk_update
    Truto->>Justworks: PUT /deductions/bulk
    Justworks-->>Truto: Return 200 OK (Success Array)
    Truto-->>Claude: JSON response
    Claude->>User: "Successfully updated 14 employee deductions to 3%."

Scenario 2: Payroll Variance Analysis

Finance teams spend significant time reconciling pay periods, looking for anomalies in gross pay or employer taxes before finalizing the books. Claude can ingest the payroll reporting endpoints to summarize these variances autonomously.

"Analyze the payrolls for Q2 2026. Find the payroll run with the highest total employer taxes. For that specific run, list the top three employees by gross pay and provide the exact dollar amounts of their net pay."

Step-by-step execution:

1. Claude calls list_all_justworks_payrolls, passing the Q2 start and end dates.
2. It analyzes the returned employer_taxes fields (converting the integer cents back into dollars for its own reasoning process) and identifies the payroll ID with the highest value.
3. Claude calls list_all_justworks_paystubs using the identified payroll_id.
4. It sorts the array of paystubs by the gross_pay field in descending order to isolate the top three earners.
5. Because the initial list only provides IDs, Claude calls get_single_justworks_paystub_by_id for those three specific paystubs to extract the precise net pay and line items.
6. Claude formats the raw cents data into human-readable currency strings and presents the final analysis to the user.

Strategic Wrap-Up

Building an AI agent that can reliably automate payroll and HR tasks requires more than just passing an API key to an LLM. The Justworks API demands strict adherence to scope-gating, complex integer arithmetic for financial data, and specific async patterns.

By leveraging Truto's managed MCP architecture, you offload the burden of OAuth lifecycles, schema management, and API drift. Truto dynamically translates Justworks's API realities into perfectly typed, strictly documented MCP tools, ensuring Claude performs exactly as intended without hallucinating fields or violating data formats.

Whether you are building internal automation for your finance team or deploying customer-facing AI agents, managed MCP gives your models secure, scalable access to Justworks data from day one.