Connect Justworks to ChatGPT: Manage Payroll, Members & Time Off

If you want to connect Justworks to ChatGPT so your AI agents can audit payroll runs, manage employee directories, adjust deductions, and generate time off reports, you need a Model Context Protocol (MCP) server. This server acts as the critical translation layer between ChatGPT's JSON-RPC tool calls and the highly specific REST payload structures of the Justworks API.

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

Giving a Large Language Model (LLM) read and write access to a core Human Resources Information System (HRIS) and payroll platform is a severe engineering challenge. You must handle complex authorization scopes, asynchronous report polling, and unforgiving integer-based currency formatting. You can either spend weeks building, hosting, and maintaining a custom MCP server to map these constraints, or you can use a managed infrastructure layer.

This guide breaks down exactly how to use Truto to generate a secure, authenticated MCP server for Justworks, connect it natively to ChatGPT, and execute complex payroll and HR workflows using natural language.

The Engineering Reality of the Justworks API

A custom MCP server is essentially a self-hosted API proxy layer. While the open MCP standard provides a predictable way for LLMs to discover and invoke tools, implementing that standard against the reality of the Justworks API introduces specific technical hurdles that break basic CRUD assumptions.

If you decide to build a custom MCP server for Justworks in-house, you own the entire API lifecycle. Here are the specific integration quirks that make the Justworks API uniquely difficult to expose to an AI agent:

Silent Field Omission and Granular Scopes

Unlike APIs that return HTTP 403 Forbidden when you request a field you do not have permission to view, the Justworks API silently drops fields from the response payload. For example, if an agent calls the /members endpoint but the underlying OAuth token lacks the member.detail:read scope, the API will still return a 200 OK, but fields like addresses, emails, and phones will simply be missing.

If your MCP tool schemas do not explicitly account for this, the LLM will hallucinate contact information or assume the fields are blank in the source system, leading to downstream workflow failures.

Strict Integer and Decimal Constraints for Payroll

When creating payroll deductions via the API, Justworks enforces highly specific payload formatting that LLMs notoriously struggle with if not given strict JSON schema constraints.

Fixed deduction amounts must be sent as integers in cents (e.g., 4500 equals $45.00). However, percentage-based deductions carry exactly four decimal places (e.g., 37000 equals 3.7%). If an LLM incorrectly assumes standard floating-point representation, an attempt to deduct $45.00 might result in a $0.45 deduction, or a 3.7% deduction might fail validation entirely. Your MCP server must inject these explicit formatting rules into the tool schemas.

Asynchronous Reporting Polling

Time off balances and certain historical HR reports in Justworks are not available via standard synchronous GET requests. You must first issue a POST request to start an asynchronous job, which returns a report_id. You must then poll a GET endpoint with that report_id until the status returns as ready.

LLMs operate in a conversational context. Exposing asynchronous reporting requires building multi-step tool definitions that instruct the LLM to call the POST tool, wait, and repeatedly call the GET tool. If you do not map this orchestration explicitly in the MCP tool descriptions, the LLM will fail to retrieve the data.

Rate Limit Passthrough Behavior

When executing high-volume operations - like auditing paystubs across hundreds of employees - you will encounter Justworks rate limits.

It is critical to note that Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Justworks API returns an HTTP 429 (Too Many Requests), Truto passes that error directly to the caller. Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The caller (or the orchestrating AI agent) is entirely responsible for interpreting these headers and executing retry or backoff logic.

Justworks to ChatGPT Quickstart Guide

If you want the fastest path from a fresh Truto account to ChatGPT successfully calling the Justworks API, follow these steps.

What you need:

• A Truto account with API access.
• A Justworks admin account capable of approving the OAuth consent screen.
• A ChatGPT Pro, Plus, Business, Enterprise, or Education seat with Developer mode enabled.

Step 1: Connect Justworks as an Integrated Account

Before you can route traffic to Justworks, you need an established OAuth connection. In the Truto dashboard, open Integrated Accounts -> New Integrated Account, select Justworks, and complete the OAuth flow. Truto securely stores the refresh token and automatically refreshes access tokens before they expire.

Make a note of your integrated_account_id. This ID represents the isolated Justworks tenant you just connected.

Step 2: Generate the Justworks MCP Server

You must generate a secure, tokenized MCP endpoint scoped specifically to this Justworks account. You can do this via the Truto UI or via the API.

Method A: Via the Truto UI

1. Navigate to the integrated account page for your Justworks connection.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration (e.g., name, allowed methods, tag filters).
5. Click save and copy the generated MCP server URL (it will look like https://api.truto.one/mcp/<token>).

Method B: Via the API You can dynamically generate the server by making a POST request to Truto. This is useful for programmatically provisioning servers for multiple customers.

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": "Justworks for ChatGPT",
    "config": {
      "methods": ["read", "write"],
      "tags": ["payroll", "members", "time_off"]
    }
  }'

The response will return the secure URL:

{
  "id": "abc-123",
  "name": "Justworks for ChatGPT",
  "config": { "methods": ["read", "write"] },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6..."
}

Treat this URL as a sensitive credential. It encodes the routing and authentication required to execute tools against the Justworks API.

Step 3: Connect the MCP Server to ChatGPT

Now that you have your secure MCP URL, you must register it with your LLM client.

Method A: Via the ChatGPT UI

1. Open ChatGPT and navigate to Settings -> Apps -> Advanced settings.
2. Toggle on Developer mode.
3. Under MCP servers / Custom connectors, click Add a new server.
4. Enter a name (e.g., "Justworks (Truto)").
5. Paste the Truto MCP URL into the Server URL field and click Save.

ChatGPT will immediately ping the endpoint, execute the initialize handshake, and request the tools/list to populate its context window with the available Justworks operations.

Method B: Via Manual Config File If you are running a local agentic framework or using a CLI tool that expects a standard MCP configuration file, you can register the endpoint using the official Server-Sent Events (SSE) transport wrapper:

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

Security and Access Control

Giving an AI agent unconstrained access to a payroll system is a massive security risk. Truto provides four layers of configuration on the MCP token to restrict what the LLM can do:

• Method Filtering (config.methods): Restrict the server to specific HTTP verbs. Pass ["read"] to allow get and list operations while blocking all create, update, and delete tools. This prevents the LLM from accidentally modifying payroll data.
• Tag Filtering (config.tags): Restrict the server to specific resource domains. Pass ["time_off"] to expose absence requests while hiding salaries and bank accounts.
• Extra Authentication (require_api_token_auth): By default, the MCP URL alone authenticates requests. If you enable this flag, the client must also pass a valid Truto API token in the Authorization header. This prevents unauthorized execution if the URL leaks in application logs.
• Time-To-Live (expires_at): Set an ISO datetime string to create a temporary, short-lived MCP server. Once the timestamp passes, the server automatically self-destructs and the KV storage entries are purged.

Hero Tools for Justworks

Truto derives tool definitions dynamically from the Justworks API documentation, merging JSON schemas and parameter requirements into standard MCP representations. Here are the highest-leverage tools available for ChatGPT to call.

List All Members (list_all_justworks_members)

This tool retrieves a paginated directory of employees, contractors, and owners within the connected company. It supports cursor pagination and filtering by updated dates or active status. The LLM must be aware that detailed fields (like addresses) are omitted if the member.detail:read scope is missing.

"Get a list of all currently active contractors in the Justworks directory. Do not include terminated members."

Get Single Member By ID (get_single_justworks_member_by_id)

When you need deep context on a specific employee, this tool retrieves their full profile, including their current pay rate, employment history, job title, and manager ID. It requires the internal member_... ID format.

"Fetch the full profile for member ID member_xyz123. Tell me who their direct manager is and what their current department is."

List All Payrolls (list_all_justworks_payrolls)

This tool queries historical and upcoming payroll runs. It requires a hard start_date and end_date in YYYY-MM-DD format. It returns critical ledger data including gross pay, net pay, employer taxes, and debit dates (all represented as integers in cents).

"List all payroll runs that were processed between January 1, 2024, and January 31, 2024. Summarize the total gross pay across all runs."

List All Deductions (list_all_justworks_deductions)

This tool allows the agent to inspect active payroll deductions across the company. It can be filtered by member_id or deduction_type. The LLM can use this to audit whether a specific employee has an active 401k or healthcare deduction.

"Show me all active deductions for member ID member_abc789. Are there any deductions categorized as a transit benefit?"

Create a Deduction (create_a_justworks_deduction)

This write-enabled tool allows the agent to insert new payroll deductions. The schema enforces strict validation: it requires an array of items containing the member ID, deduction type code, frequency, and amount type (fixed or percent).

"Create a new fixed deduction for member ID member_xyz123. The deduction is for $50.00 (which you must pass as 5000 cents) starting on March 1, 2024. The frequency should be per_pay_period."

List Time Off Requests (list_all_justworks_time_off_requests)

This tool queries the status of employee PTO, sick leave, and other absences. It requires a date range and can filter by status (requested, approved, declined). It returns the total duration along with the unit type (minutes, hours, days).

"List all approved time-off requests between June 1 and June 15. Calculate how many total days of PTO have been approved for that window."

For the complete inventory of available Justworks tools and exact schema definitions, visit the Justworks integration page.

Workflows in Action

AI agents shine when orchestrating multi-step API operations. By connecting Justworks to ChatGPT via Truto, you unlock autonomous HR and finance workflows.

Workflow 1: Auditing Terminated Employees and Paystubs

An HR administrator needs to verify that recently terminated employees have received their final paystubs and have no active recurring deductions.

"Find all members whose status was updated to terminated in the last 30 days. For each terminated member, list their active deductions and confirm the gross amount of their last paystub."

Execution Steps:

1. ChatGPT calls list_all_justworks_members filtering by status: terminated and updated_at_gte (set to 30 days ago).
2. For each returned member_id, ChatGPT calls list_all_justworks_deductions to audit for any remaining active charges that need cancellation.
3. ChatGPT calls list_all_justworks_payrolls for the recent month to capture the latest payroll_id.
4. ChatGPT calls list_all_justworks_paystubs passing the payroll_id and filters the result to find the specific member's final gross pay.
5. ChatGPT presents a clean markdown summary of the audit to the administrator.

Workflow 2: Asynchronous Time Off Balance Reporting

An engineering manager wants to check if their team has enough accrued vacation time before approving a major feature sprint.

"Generate a time off balance report as of today. Check the status until it is ready, then tell me the available vacation balances for my direct reports."

Execution Steps:

sequenceDiagram
    participant LLM as ChatGPT
    participant MCP as Truto MCP Server
    participant API as Justworks API
    LLM->>MCP: Call create_a_justworks_time_off_balance_report (as_of_date)
    MCP->>API: POST /time_off_balance_reports
    API-->>MCP: HTTP 202 Accepted (report_id: 9876)
    MCP-->>LLM: Return report_id: 9876
    LLM->>MCP: Call get_single_justworks_time_off_balance_report_by_id (9876)
    MCP->>API: GET /time_off_balance_reports/9876
    API-->>MCP: HTTP 200 (status: pending)
    MCP-->>LLM: Return status: pending
    Note over LLM, API: ChatGPT waits 5 seconds and retries
    LLM->>MCP: Call get_single_justworks_time_off_balance_report_by_id (9876)
    MCP->>API: GET /time_off_balance_reports/9876
    API-->>MCP: HTTP 200 (status: ready, data: [...])
    MCP-->>LLM: Return balance data

1. ChatGPT invokes create_a_justworks_time_off_balance_report to trigger the asynchronous job generation on the Justworks backend.
2. Justworks returns a report_id.
3. ChatGPT invokes get_single_justworks_time_off_balance_report_by_id using the ID. If it returns pending, the LLM waits and executes the tool again.
4. Once the payload returns ready, ChatGPT extracts the balances and summarizes the available PTO for the team.

Strategic Wrap-Up

Exposing an enterprise HRIS and payroll API to an AI agent requires more than just formatting JSON. You must enforce granular OAuth scopes, handle complex asynchronous polling patterns, normalize rate limit errors for retry logic, and guarantee that LLMs format integers correctly to avoid catastrophic payroll mistakes.

Building this orchestration layer from scratch means maintaining constant vigilance over the Justworks API lifecycle. Using Truto's auto-generated MCP servers allows you to bypass the infrastructure burden. Truto translates the Justworks documentation directly into standardized, secure JSON-RPC tools, letting you focus on prompt engineering and workflow design rather than managing API state and token refresh loops.