Connect PayFit to Claude: Manage HR Contracts and Collaborators

If you need to connect PayFit to Claude to automate HR administration, contract generation, or payroll auditing, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's internal tool-calling mechanics and PayFit's REST APIs. You can either spend weeks building and maintaining 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 PayFit to ChatGPT or explore our broader architectural overview on connecting PayFit to AI Agents.

Giving a Large Language Model (LLM) read and write access to a sprawling HR ecosystem like PayFit is a massive engineering challenge. You have to handle OAuth 2.0 token lifecycles, map massive nested JSON schemas to MCP tool definitions, and deal with PayFit's specific regional data models. Every time PayFit updates an endpoint 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 PayFit, connect it natively to Claude Desktop, and execute complex HR workflows using natural language.

The Engineering Reality of the PayFit 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 over JSON-RPC 2.0, the reality of implementing it against vendor APIs is painful. You are not just integrating "HR" - you are integrating a highly opinionated, region-specific payroll engine with its own design patterns and quirks.

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

Fragmented Regional Endpoints and Schemas PayFit's API is heavily partitioned by country. A contract in the UK requires specific auto-enrolment documentation and income tax records (P45, P60). A contract in France requires complex natureContratDsn, idcc, and estCadreDirigeant fields. If you expose a generic "Create Contract" tool to Claude without enforcing regional boundaries, the model will hallucinate generic HR fields that the PayFit API will reject. You have to carefully map region-specific endpoints (like /companies/fr/{id} or /contracts/fr) to distinct, clearly documented tools.

Asynchronous Resource Provisioning Unlike a standard CRUD application where creating a record returns it immediately, PayFit's infrastructure relies on asynchronous job processing. When you create a basic PayFit contract, the API returns an empty 201 Created response. The contract is not immediately available - it takes between 2 to 5 minutes to propagate through PayFit's backend before it can be updated or completed by an admin. If you do not build specific polling logic or context into your MCP server, Claude will attempt to update the contract milliseconds after creation and fail entirely.

Binary File Streams in REST Responses Many of the highest-value operations in PayFit involve documents: payslips, billing declarations, and payment files. PayFit's endpoints for these (such as /payslips/{id}) do not return JSON metadata containing a download URL; they stream raw binary PDF or CSV data directly in the HTTP response. Handling these streams, encoding them, and passing them reliably back to Claude via the MCP JSON-RPC protocol requires non-trivial middleware engineering.

Instead of building this from scratch, you can use Truto. Truto normalizes authentication, pagination, and data schemas, exposing PayFit's endpoints as ready-to-use MCP tools with explicitly formatted documentation schemas that guide the LLM.

How to Generate a PayFit MCP Server with Truto

Truto dynamically generates MCP tools from PayFit's underlying API resources. There is no hand-coded translation layer - tools are built dynamically based on documented endpoints.

You can generate an MCP server scoped to a specific PayFit account using either the Truto UI or the API.

Method 1: Via the Truto UI

For administrators and non-developers, the UI is the fastest way to provision a server:

1. Log into your Truto dashboard.
2. Navigate to the Integrated Accounts page and select the connected PayFit account.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration. You can filter tools by methods (e.g., read, write) or tags (e.g., contracts, billing).
6. Copy the generated MCP server URL (e.g., https://api.truto.one/mcp/abc123def456...).

Method 2: Via the Truto API

For engineering teams building automated provisioning flows, you can generate MCP servers programmatically. Make a POST request to /integrated-account/:id/mcp.

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": "PayFit Read-Only Ops",
    "config": {
      "methods": ["read"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The Truto API will generate a secure, hashed token and return the ready-to-use URL:

{
  "id": "mcp_token_xyz789",
  "name": "PayFit Read-Only Ops",
  "config": { "methods": ["read"] },
  "expires_at": "2026-12-31T23:59:59.000Z",
  "url": "https://api.truto.one/mcp/abc123def456..."
}

How to Connect the PayFit MCP Server to Claude

Once you have the Truto MCP URL, you need to configure Claude to use it. The URL contains a cryptographic token that securely identifies the PayFit account and tool scope. You do not need to configure OAuth or handle credentials on the client side.

Method A: Via the Claude UI

If you are using a consumer-facing AI interface that supports MCP (like the Claude Desktop application or ChatGPT Advanced settings):

1. In Claude, navigate to Settings → Integrations → Add MCP Server.
2. Provide a recognizable name (e.g., "PayFit Production").
3. Paste the Truto MCP server URL.
4. Click Add.

Claude will immediately hit the initialize and tools/list JSON-RPC endpoints to discover all available PayFit operations.

Method B: Via Manual Config File

If you are deploying AI agents locally or orchestrating multi-agent systems using Claude Desktop's backend, you can modify the configuration file directly.

Edit your claude_desktop_config.json file. Because Truto MCP URLs natively support Server-Sent Events (SSE) over HTTP, you can use the official @modelcontextprotocol/server-sse wrapper to handle the transport.

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

Restart Claude Desktop. The PayFit tools are now injected directly into the LLM's context window.

PayFit Hero Tools for Claude

Truto provides dozens of tools for PayFit, mapping deeply to the REST API. Here are the highest-leverage tools your agents can use immediately.

get_single_pay_fit_companies_fr_by_id

Fetches critical baseline data for a French PayFit company, including the siren, siret, and health insurance proration methods. This is often the required first step before an agent can orchestrate downstream French-specific HR tasks.

Fetch the basic company information for PayFit company ID 98765, and tell me their SIRET number and health insurance proration method.

get_single_pay_fit_contract_by_id

Retrieves a comprehensive snapshot of a specific employment contract. The LLM gets the full JSON object including jobName, status, startDate, endDate, probationEndDate, and detailed time information fields.

Pull the contract details for contract ID 555444. Summarize the employee's job title, their probation end date, and whether the contract is currently active.

list_all_pay_fit_contracts

Lists all active (and optionally in-progress) contracts for the company. This is heavily utilized by agents running audits or compiling headcount reports.

List all contracts for the company. Filter the results to only show me employees who have a start date in the year 2025.

create_a_pay_fit_contract

Creates a basic employment contract for an existing collaborator. Note that this requires collaborator_id, jobTitle, and startDate. Truto's documentation explicitly tells Claude that this operation takes 2-5 minutes to finalize on PayFit's backend.

Create a new contract for collaborator ID 111222. The job title is 'Senior DevOps Engineer' and the start date is 2025-06-01.

list_all_pay_fit_absences

Retrieves absence records for the company. By default, it returns approved absences, providing the contractId, startDate, endDate, and absence type.

Pull the approved absences for the company. Identify which contract ID has the most days off scheduled for Q3 2025.

get_single_pay_fit_payslip_by_id

Fetches a specific employee's payslip as a raw binary PDF file. This tool is critical for downstream compliance agents that need to store or email financial documents. It requires the collaborator_id, contract_id, and payslip id.

Fetch the PDF payslip for collaborator ID 333, contract ID 444, payslip ID 555. Let me know when the download is complete.

To view the complete inventory of PayFit endpoints, schemas, and parameters supported by Truto, visit the PayFit integration page.

Workflows in Action

Giving an LLM isolated tools is interesting. Giving it a sequence of tools to execute complex, multi-step business logic is where MCP becomes an operational mandate.

Here is how AI agents handle real-world PayFit workflows using Truto's MCP server.

Scenario 1: New Employee Onboarding Audit

HR Administrators spend hours cross-referencing platforms to ensure new hires are provisioned correctly. An AI agent can audit the PayFit instance to ensure an onboarding flow was completed.

Check if there is a collaborator named 'Alice Smith'. If she exists, find her active contract. If she has a contract, verify that her health insurance affiliation is set up correctly.

Step-by-step execution:

1. Claude calls list_all_pay_fit_companies_collaborators to scan the directory for Alice Smith and retrieve her id and associated contracts array.
2. Claude extracts her contract_id and calls get_single_pay_fit_contract_by_id to verify the contract status is active.
3. Claude calls list_all_pay_fit_health_insurance_contracts to cross-reference her ID against active health insurance policies.
4. Result: The agent returns a natural language summary confirming Alice is fully provisioned, or highlighting that her health insurance affiliation is missing.

Scenario 2: End-of-Month Payroll Verification

Finance teams need to verify payroll statuses before closing the month. The agent can aggregate data automatically across multiple endpoints.

Check the payroll status for the pay period 202511. If the status is completed, list all French-specific contracts and compile a summary of their natureContratDsn classifications.

Step-by-step execution:

1. Claude calls list_all_pay_fit_payroll_status with the query parameter date: "202511".
2. The API returns { "status": "completed", "executionEndDate": "2025-11-28" }.
3. Seeing the completed status, Claude proceeds to call list_all_pay_fit_contracts_frs to fetch the localized contract data.
4. Claude parses the JSON response, aggregates the natureContratDsn fields across all returned objects, and outputs a formatted table.
5. Result: The user receives a definitive confirmation that payroll ran, along with an exact breakdown of contract classifications for compliance reporting.

graph TD
    A[User Prompt: Verify Payroll 202511] --> B[Claude parses intent]
    B --> C{Call: list_all_pay_fit_payroll_status}
    C -->|status: completed| D{Call: list_all_pay_fit_contracts_frs}
    C -->|status: not_completed| E[Return warning to user]
    D --> F[Aggregate natureContratDsn fields]
    F --> G[Output Table to User]

Security and Access Control

Exposing an HR platform containing PII and salary data to an LLM requires strict security guardrails. Truto's MCP architecture enforces control at the server infrastructure layer, not just the client level.

• Method Filtering: When generating the server via the API (config.methods), you can strictly limit the MCP server to specific HTTP verbs. Creating a server with ["read"] ensures Claude physically cannot execute create_a_pay_fit_contract or update health insurance data, preventing accidental or malicious writes.
• Tag Filtering: You can restrict the server scope by functional tags (config.tags). For example, you can provision an MCP server that only has access to the absences tag, entirely masking payslips and contracts from the LLM.
• Require API Token Auth: By default, anyone with the generated Truto MCP URL can invoke the tools. By setting require_api_token_auth: true, the MCP client must inject a valid Truto Bearer token into the headers. This prevents unauthorized execution if the URL is leaked in internal logs.
• Time-to-Live (TTL) Servers: Using the expires_at parameter, you can generate temporary MCP servers. Truto's internal scheduler automatically shreds the server credentials and KV storage entries at the expiration time. This is ideal for granting a contractor temporary audit access.

Handling Rate Limits

PayFit enforces API rate limits to maintain platform stability. When building AI agents, it is critical to understand how these limits are handled in the integration layer.

Truto does not absorb, queue, or silently retry requests that hit rate limits. If an LLM fires too many requests in parallel and PayFit rejects them, Truto passes the HTTP 429 Too Many Requests error directly back to the caller.

However, Truto normalizes the upstream vendor's proprietary headers into a standardized IETF format. Your MCP client will receive ratelimit-limit, ratelimit-remaining, and ratelimit-reset. The agent orchestrator (e.g., LangGraph, CrewAI, or your custom client) is responsible for reading these headers and implementing backoff and retry logic. This explicit failure model ensures your AI agents do not hang indefinitely waiting for phantom background queues.

Ship AI Integrations Faster

Connecting Claude to PayFit using a custom MCP server means owning a massive matrix of OAuth tokens, binary file handlers, and region-specific JSON schemas. Truto abstracts the entire API lifecycle, turning PayFit's fragmented HR endpoints into a unified, secure, LLM-ready toolset.

Stop writing custom integration code and start orchestrating workflows.