Connect PeopleForce to Claude: Manage Lifecycle, Leave & Salaries

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

If you need to connect PeopleForce to Claude to automate HR lifecycle management, audit payroll salaries, or orchestrate complex leave approvals, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude’s natural language tool calls and the highly structured, relational REST APIs of PeopleForce.

You can either build and maintain this infrastructure yourself, constantly patching breaking changes and pagination logic, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL.

Giving a Large Language Model (LLM) read and write access to a sprawling Human Resources Information System (HRIS) like PeopleForce is a significant engineering challenge. You must handle complex authorization schemas, map nested JSON objects for employee compensation, and manage strict operational workflows like employee termination. Every time PeopleForce releases an API update or introduces a new v4 endpoint, you have to update your server code, redeploy, and test the integration to ensure agent operations do not fail silently in production.

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

The Engineering Reality of the PeopleForce 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 HRIS APIs is painful. PeopleForce is built to manage the entire employee lifecycle—from ATS recruitment to core HR, performance, and time tracking. Its API structure is a direct reflection of that immense domain complexity.

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

Fragmented API Versions and Inter-related Modules PeopleForce divides its API across multiple versions (v2, v3, v4) depending on the functional module. Core HR operations might utilize v3, while some specific public integrations (like historical legacy endpoints or advanced custom tables) rely on a mix of versions. More importantly, these entities are deeply relational. You cannot simply instruct an LLM to "Assign John Doe to the Engineering department." The agent must first query the list of departments, extract the correct internal department_id, query the user's employee_id, and construct a payload linking the two. A proper MCP layer must expose these lookup operations as discrete tools.

Custom Fields and Internal Name Indexing Unlike basic CRUD applications, HR systems are heavily customized per organization. In PeopleForce, custom employee fields are returned as a flat JSON object keyed not by a human-readable label, but by an internal_name (e.g., cf_favorite_snack or custom_field_102). An LLM has no inherent context to parse these keys. To interact with custom data, the agent must be provided a tool like list_all_people_force_employee_fields to dynamically map the underlying schema definitions to the active employee record.

Strict Compensation Scope Gating Endpoints related to salaries and additional_compensations enforce rigorous access controls. If your API token lacks explicit compensation access, these endpoints will throw hard HTTP 403 Forbidden errors rather than returning empty arrays. In an automated agent loop, unhandled 403 errors will cause the LLM to hallucinate data or crash the workflow. Exposing these operations via MCP requires careful scoping and error passing.

Rate Limiting Reality PeopleForce rate limits are applied strictly per tenant. Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream PeopleForce API returns an HTTP 429, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit information into standardized IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). The LLM orchestrator or Claude client is completely responsible for handling the retry and backoff logic using the provided ratelimit-reset timestamp.

Building the PeopleForce MCP Server via Truto

Truto derives MCP tools dynamically from the API documentation and configuration of the connected integration. Tools are not hard-coded; they are generated dynamically, meaning your AI agent always has access to the most accurate schema representations of the PeopleForce API.

Truto MCP servers are scoped to a single integrated account (a specific tenant connection). You can spin up an MCP server manually via the Truto Dashboard or programmatically via the API.

Method 1: Creating via the Truto UI

For ad-hoc agent testing or internal administrative workflows, the UI is the fastest path:

1. Log into your Truto dashboard and navigate to the integrated account page for your active PeopleForce connection.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Configure your server constraints. You can restrict the server to specific operations (e.g., only read operations for safety) or specific functional tags.
5. Copy the generated secure MCP Server URL (e.g., https://api.truto.one/mcp/a1b2c3d4e5f6...).

Method 2: Creating via the API

For engineering teams building multi-tenant AI products, MCP servers should be provisioned dynamically. When a new HR admin authenticates their PeopleForce account, your backend can issue a request to generate a scoped MCP token.

Make a POST request to /integrated-account/:id/mcp with your desired configuration:

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": "Claude PeopleForce Lifecycle Manager",
    "config": {
      "methods": ["read", "write"],
      "require_api_token_auth": false
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The API provisions the resources in distributed edge storage and returns a ready-to-use URL:

{
  "id": "mcp_pf_8f99a1b",
  "name": "Claude PeopleForce Lifecycle Manager",
  "url": "https://api.truto.one/mcp/f8e7d6c5b4a3...",
  "config": { "methods": ["read", "write"] }
}

Connecting the MCP Server to Claude

Once the MCP URL is generated, Claude needs to be instructed on how to connect to it. Communication happens entirely over standard HTTP POST via JSON-RPC 2.0. You can establish the connection using the Claude UI or via a configuration file.

Method A: Via the Claude UI

If you are using Claude Desktop or the web interface with Custom Connectors enabled:

1. Open Claude and navigate to Settings → Integrations (or Connectors).
2. Click Add MCP Server or Add custom connector.
3. Paste your Truto MCP Server URL.
4. Click Add. Claude will instantly execute the initialize and tools/list handshakes, rendering all permitted PeopleForce tools available in your chat context.

Method B: Via the Claude Desktop Config File

For power users and local development, you can hardcode the configuration using the Server-Sent Events (SSE) transport wrapper provided by the Model Context Protocol SDK.

Open your claude_desktop_config.json file (typically found in ~/Library/Application Support/Claude/ on macOS or %APPDATA%\Claude\ on Windows) and append the following configuration:

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

Restart Claude Desktop. The agent is now securely tethered to your PeopleForce tenant.

Hero Tools for PeopleForce Workflows

Truto exposes the entirety of the PeopleForce API as MCP tools. The input namespace is flat; query parameters and request body schemas are intelligently parsed so the LLM simply provides arguments without needing to structure HTTP requests.

Here are the highest-leverage tools for automating HR operations.

1. list_all_people_force_employees

The backbone of directory management. This tool retrieves employee records, supporting advanced filtering by status, manager, hire date, and custom fields. By default, it returns active employees.

Usage Note: This is often the first step in an agentic chain to resolve an employee's human-readable name into their internal id.

"Find the employee record for Jane Doe. Make sure to retrieve her current department and reporting manager details."

2. get_single_people_force_employee_by_id

Retrieves the deep profile of a specific employee, including department ancestors, direct reports, historical custom field values, and meta-information.

Usage Note: Use this when you need exhaustive context on a single user before making structural HR decisions.

"Pull the complete employee profile for the user with ID 4059, including their custom fields and direct reports."

3. list_all_people_force_employee_salaries_employees

Fetches the complete salary history of a specific employee. Returns effective dates, amounts, currency codes, pay schedules, and overtime statuses.

Usage Note: The integration token used must possess compensation-level access. If it does not, the PeopleForce API will reject the request. The LLM must supply the employee_id.

"Audit the salary history for employee ID 4059. List their current base pay and note any historical adjustments made in the last 2 years."

4. create_a_people_force_public_leave_requests_v_3

Allows the agent to formally submit time-off requests. It requires intricate nested data detailing the precise start/end dates, the leave type, and day-by-day entry breakdowns.

Usage Note: The agent must resolve the employee_id and the leave_type_id before constructing the complex leave_request_entries array.

"Submit a leave request for employee ID 4059 for sick leave from October 12th to October 14th. The leave type ID is 12."

5. create_a_people_force_recruitment_candidates_recruitment

Bridges the core HR system with ATS operations. It creates a new candidate profile in the recruitment pipeline, mapping emails, phone numbers, resumes, and custom fields. Duplicates are auto-matched upstream by email.

Usage Note: Essential for parsing inbound candidate resumes via text and pushing the structured output directly into the recruitment funnel.

"Create a new candidate profile in PeopleForce for Alex Mercer. Their email is alex@example.com and they are applying for the Senior Developer role."

6. list_all_people_force_public_audits_v_3

Extracts system-wide audit logs. This is critical for security and compliance, detailing record creations, updates, deletions, and the exact employee who initiated the action.

Usage Note: Use this for IT security reviews or SOC 2 evidence gathering.

"Pull the most recent audit logs from PeopleForce to verify who updated the compensation records this week."

7. create_a_people_force_employee_terminates_terminate

Orchestrates the delicate process of employee offboarding. It schedules a termination to take effect on a specific date, requiring the termination_type_id, termination_reason_id, and a rehire eligibility flag.

Usage Note: Because this is a destructive/terminal action, it is highly recommended to gate this tool behind a "Human in the loop" approval framework, or restrict it via Truto's method filtering on less secure environments.

"Schedule a termination for employee ID 8832 effective this Friday. Mark them as eligible for rehire and use termination reason ID 4."

For the complete, exhaustive list of available tools—including asset assignments, pulse surveys, time sheets, and custom tables—view the PeopleForce integration page.

Workflows in Action

By leveraging Claude's multi-step reasoning capabilities with Truto’s MCP layer, you can transform multi-click HR chores into autonomous, conversational workflows.

Workflow 1: Leave Discrepancy & Salary Audit

Persona: Finance / HR Admin

"Claude, check if Jane Smith has enough PTO balance for next week. If she does, review her current salary data to ensure her upcoming pay cycle won't be affected by unpaid leave rules."

1. list_all_people_force_employees: Claude searches for "Jane Smith" to retrieve her internal id.
2. list_all_people_force_employee_leave_balances_employees: Claude passes the employee_id to query her current leave balances against specific policies.
3. list_all_people_force_employee_salaries_employees: After confirming her leave balance is sufficient, Claude fetches her compensation data to review her pay schedule.

sequenceDiagram
    participant Admin
    participant Agent as Claude Agent
    participant MCP as Truto MCP
    participant Upstream as "PeopleForce API"

    Admin->>Agent: "Check PTO balance & salary for Jane Smith"
    Agent->>MCP: Call tools/call (list_all_people_force_employees)
    MCP->>Upstream: GET /api/v3/employees?search=Jane
    Upstream-->>MCP: Returns employee_id: 812
    MCP-->>Agent: JSON Response
    Agent->>MCP: Call tools/call (list_all_people_force_employee_leave_balances_employees)
    MCP->>Upstream: GET /api/v3/employees/812/leave_balances
    Upstream-->>MCP: Returns balances
    MCP-->>Agent: JSON Response
    Agent->>MCP: Call tools/call (list_all_people_force_employee_salaries_employees)
    MCP->>Upstream: GET /api/v3/employees/812/salaries
    Upstream-->>MCP: Returns compensation records
    MCP-->>Agent: JSON Response
    Agent-->>Admin: "Jane has 40 hours PTO remaining. Her salary of $80k/yr is processed semi-monthly. Unpaid rules do not apply."

Workflow 2: Cross-Department Asset & Offboarding Audit

Persona: IT Support / SysAdmin

"Claude, we are preparing to offboard John Doe. Please retrieve the list of all physical assets assigned to him and schedule his termination for this Friday."

1. list_all_people_force_employees: Claude resolves "John Doe" to his id.
2. list_all_people_force_employee_assets_employees: Claude queries the asset registry to find all laptops, monitors, or hardware assigned to that ID.
3. list_all_people_force_public_termination_reasons_v_3: Claude looks up the valid termination reasons configured in the tenant.
4. create_a_people_force_employee_terminates_terminate: Claude stages the termination payload using the resolved IDs and effective dates.

Security and Access Control

When connecting powerful AI models to sensitive HR systems like PeopleForce, security must be tightly governed at the infrastructure level. Truto MCP servers enforce granular controls:

• Method Filtering (config.methods): Restrict servers entirely to read operations, guaranteeing that rogue agent logic cannot accidentally trigger employee terminations or wipe salary data.
• Tag Filtering (config.tags): If you only want Claude managing ATS workflows, you can filter the server to only expose tools tagged with recruitment, completely hiding core HR modules.
• Time-to-Live (expires_at): Ideal for contractors or temporary AI workflows. The server token automatically expires and the infrastructure self-destructs at the assigned ISO datetime.
• Double Authentication (require_api_token_auth): By default, the cryptographically hashed URL acts as the bearer token. Enabling this flag forces the MCP client to also pass a valid Truto API token in the Authorization header, preventing leaked URLs from being exploited.

Moving Forward

Manually scripting integrations against specialized HR APIs results in brittle, high-maintenance codebases. By abstracting the endpoint logic, payload flattening, and documentation mapping into a unified MCP protocol layer, you empower your AI agents to interact with PeopleForce seamlessly and safely.

Let your models focus on intelligent HR reasoning, and let Truto handle the integration infrastructure.