> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.deel.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.deel.com/_mcp/server.

# Tools reference

> Browse and understand the tools available on the Deel MCP server

The Deel MCP server exposes tools that map to Deel API operations. Each tool accepts structured input parameters and returns JSON results. The AI client selects and invokes the appropriate tool based on the user prompt.

## How tools work

MCP tools follow the JSON-RPC 2.0 protocol. When an AI agent determines that a Deel tool is needed, it sends a `tools/call` request to the MCP server with the tool name and input parameters. The server executes the corresponding API operation and returns the result.

### Request format

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "listOfContracts",
    "arguments": {}
  }
}
```

### Response format

A successful tool invocation returns a result with content:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"data\": [{\"id\": \"abc123\", \"title\": \"Software Engineer\", ...}]}"
      }
    ]
  }
}
```

If the tool execution fails, the response includes an `isError` flag:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Error: Insufficient permissions. The token requires contracts:read scope."
      }
    ],
    "isError": true
  }
}
```

You do not need to construct these JSON-RPC messages manually. MCP clients handle the protocol communication automatically. This section is provided for developers building custom MCP clients or debugging tool invocations.

## Tool categories

Tools are organized by the domain they operate on. The table below groups tools by functional area.

### Contracts and hiring

| Tool name                             | Description                               |
| ------------------------------------- | ----------------------------------------- |
| listOfContracts                       | List contracts in the organization        |
| retrieveASingleContract               | Retrieve details of a specific contract   |
| createANewContract                    | Create a new contract                     |
| createContractForEOR                  | Create an EOR contract quote              |
| retrieveEorContractDetails            | Retrieve EOR contract summary             |
| amendContract                         | Amend contract details                    |
| listContractAmendments                | List amendments for a contract            |
| signContract                          | Sign a contract                           |
| retrieveContractFormForEOR            | Retrieve EOR contract form for a country  |
| retrieveContractStartDateForEOR       | Retrieve earliest EOR contract start date |
| retrieveContractAdditionalCostsForEOR | Retrieve EOR additional costs by country  |

### People and HRIS

| Tool name                                   | Description                                |
| ------------------------------------------- | ------------------------------------------ |
| getListOfPeople                             | List all people in the organization        |
| getHrisProfilePerson                        | Retrieve a person by HRIS profile ID       |
| searchUserByEmail                           | Search for a user by email                 |
| updatePersonalInformation                   | Update worker personal information         |
| updatePeoplePersonalInformationByExternalId | Update personal information by external ID |
| getLoggedInUserProfile                      | Retrieve the authenticated user profile    |
| getHrisOrganizationStructures               | Retrieve organization structure            |
| getCustomFieldFromPeopleById                | Retrieve a custom field by ID              |
| getCustomFieldsFromPeople                   | List all custom fields                     |
| GetCustomFieldValuesFromWorker              | Retrieve custom field values for a worker  |

### Time off and scheduling

| Tool name                  | Description                          |
| -------------------------- | ------------------------------------ |
| getTimeOffPolicies         | List time-off policies for a profile |
| createTimeOffRequest       | Create a time-off request            |
| updateTimeOffRequest       | Update a time-off request            |
| cancelTimeOffRequest       | Cancel a time-off request            |
| getTimeOffRequests         | List time-off requests for a profile |
| getProfileEntitlements     | Retrieve time-off entitlements       |
| getTimeoffTypeList         | List time-off types                  |
| getWorkScheduleAndHolidays | Retrieve work schedule and holidays  |
| getShifts                  | List shifts                          |
| getShiftByExternalId       | Retrieve a shift by external ID      |
| getShiftRates              | List shift rates                     |
| getShiftRateByExternalId   | Retrieve a shift rate by external ID |

### Payments and invoices

| Tool name                       | Description                               |
| ------------------------------- | ----------------------------------------- |
| getInvoiceList                  | List paid invoices                        |
| getInvoiceById                  | Retrieve invoice details by ID            |
| retrieveDeelInvoices            | List Deel fee invoices                    |
| createInvoiceAdjustment         | Create an invoice adjustment              |
| updateInvoiceAdjustment         | Update an invoice adjustment              |
| getAdjustments                  | List adjustments for a contract           |
| retrievePaymentReceipts         | List payment receipts                     |
| retrieveAPaymentBreakdown       | Retrieve payment breakdown                |
| getDetailedPaymentsReport       | Retrieve detailed payment report          |
| getContractPaymentDates         | List payment dates for a contract         |
| AddOffCyclePaymentForContract   | Add off-cycle payment for a contract      |
| getOffCyclePaymentByContractId  | Retrieve off-cycle payment by contract ID |
| getOffCyclePaymentsByContractId | List off-cycle payments for a contract    |

### Payroll

| Tool name            | Description                             |
| -------------------- | --------------------------------------- |
| getEORWorkerPayslips | Retrieve EOR worker payslips            |
| getGPWorkerPayslips  | Retrieve Global Payroll worker payslips |

### Hiring intelligence

| Tool name                                      | Description                                 |
| ---------------------------------------------- | ------------------------------------------- |
| calculateEmploymentCost                        | Calculate employment cost for a country     |
| calculateEmploymentCostForMultipleCountries    | Calculate employment costs across countries |
| calculateTakeHomePay                           | Calculate take-home pay                     |
| calculateEorVersusEntityHiringCosts            | Compare EOR versus entity hiring costs      |
| getSalaryHistogramForARoleInMultiplesCountries | Retrieve salary histogram data              |
| listEmploymentComparisonsAcrossCountries       | Compare employment across countries         |
| getHiringInsightsReportSummary                 | Retrieve hiring insights report             |
| getEorCountryValidations                       | Retrieve country hiring guide               |

### Benefits and compliance

| Tool name                                  | Description                             |
| ------------------------------------------ | --------------------------------------- |
| retrieveBenefitsByCountry                  | List benefits by country                |
| getEORContractBenefits                     | Retrieve EOR contract benefits          |
| retrieveBenefitsForEmployee                | Retrieve benefits for an employee       |
| listOfEmployeeComplianceDocuments          | List compliance documents               |
| downloadSubmittedComplianceDocument        | Download a compliance document          |
| downloadEmployeeComplianceDocumentTemplate | Download a compliance document template |
| checkVisaRequirement                       | Check visa requirements                 |
| getPolicyValidationTemplates               | Retrieve policy validation templates    |

### IT assets

| Tool name              | Description               |
| ---------------------- | ------------------------- |
| listItAssets           | List IT assets            |
| retrieveAnItAsset      | Retrieve IT asset details |
| listItHardwarePolicies | List IT hardware policies |
| listItOrders           | List IT equipment orders  |
| retrieveAnItOrder      | Retrieve IT order details |

### Onboarding and immigration

| Tool name                                   | Description                           |
| ------------------------------------------- | ------------------------------------- |
| getOnboardingDetailsByEmployeeHrisProfileId | Retrieve onboarding details           |
| listOnboardingEmployees                     | List onboarding employees             |
| listBackgroundChecksByContract              | List background checks for a contract |
| immigrationCaseDetails                      | Retrieve immigration case details     |
| immigrationVisaTypes                        | List immigration visa types           |
| immigrationDocument                         | Retrieve immigration document details |

### Organization and reference data

| Tool name                   | Description                    |
| --------------------------- | ------------------------------ |
| getCurrentOrganization      | Retrieve organization details  |
| getTeamList                 | List teams                     |
| getLegalEntityList          | List legal entities            |
| retrieveCountries           | List supported countries       |
| retrieveSupportedCurrencies | List supported currencies      |
| retrieveJobTitles           | List job titles                |
| retrieveSeniorityLevels     | List seniority levels          |
| getLookups                  | Retrieve lookup data           |
| getRecordByExternalId       | Retrieve record by external ID |
| createWorkerAccessToken     | Create a worker access token   |
| retrieveAListOfAtsOffers    | List ATS offers                |

## Next steps

#### [Error handling](/mcp/error-handling)

Handle errors when invoking MCP tools

#### [Best practices](/mcp/best-practices)

Optimize your MCP integration for production use

#### [Authorization](/mcp/authorization)

Understand scopes and permissions for tool access

#### [Connecting clients](/mcp/connecting-clients)

Configure your AI client to connect to the Deel MCP server