Merge Unified's Warp integration Merge Agent Handler's Warp MCP server

Connect your AI Agents to Warp in minutes

Merge lets you securely connect your agents to Warp and thousands of tools instantly

Start building for free

Read docs

Warp

Learn more about Merge Agent Handler

Available tools

list_benefit_deductions

List current payroll benefit deductions. Defaults to active deductions; pass the full list of statuses you want (e.g. ["active", "terminated"]) to include others. Filter by workerids (use listworkers), categories, types, healthplanids (use listhealthplans), or retirementplanids (use listretirementplans).

get_benefit_deduction

Get the current version of a company benefit deduction by ID. Use listbenefitdeductions to find valid IDs.

list_health_plans

List company health plans. Defaults to active plans; pass the full list of statuses you want (e.g. ["active", "terminated"]) to include others. Filter by types or carrier_ids (read carrier.id from an unfiltered response to find valid IDs).

get_health_plan

Get a publicly visible company health plan by ID. Use listhealthplans to find valid IDs.

list_retirement_plans

List company retirement plans. Defaults to active plans; pass the full list of statuses you want (e.g. ["active", "terminated"]) to include others. Filter by types.

get_retirement_plan

Get a company retirement plan by ID, regardless of status. Use listretirementplans to find valid IDs.

create_benefit_deduction

Create a payroll benefit deduction for a worker (use listworkers for the ID). Attach it to an existing plan via plan (use listhealthplans or listretirementplans), or pass null for a planless deduction. Fixed amounts are USD cents. There is no delete; stop a deduction with updatebenefit_deduction status 'terminated'.

update_benefit_deduction

Update a benefit deduction's name, contributions, recurrence, status, or end date. Null fields are left unchanged. The calculation type cannot change. Set status 'terminated' to stop a deduction. Use listbenefitdeductions to find valid IDs.

create_retirement_plan

Register a company retirement plan administered manually (provider 'manual'). Requires type, name, and effectivestartdate. Only one active plan per type is allowed: call listretirementplans first and reuse it. Attach deductions with createbenefitdeduction. No delete; end a plan with updateretirementplan.

update_retirement_plan

Update a manually administered retirement plan's name or dates. Null fields are left unchanged; set cleareffectiveenddate to remove the end date. Only plans with provider 'manual' can be updated. Use listretirement_plans to find valid IDs.

get_company

Get the company tied to the API key: legal and display name, unmasked EIN, contact details, business and mailing addresses, business type, and incorporation state and date. Requires the settings read permission. Takes no input.

list_custom_fields

List the custom worker field definitions your API key can read. Use this to find field IDs (and, for select/multiselect fields, valid option IDs) for setcustomfieldvalue. Archived fields are included unless status='active'.

get_custom_field

Get a custom worker field definition by ID, including its select options. Use listcustomfields to find valid IDs.

create_custom_field

Create a custom worker field definition. The field type is immutable after creation. Select and multiselect fields can include their initial options. Requires the workers:customfields permission.

update_custom_field

Update a custom worker field definition. The field type cannot be changed; create a new field instead. Changing category, accessLevel, or inputBy requires the manage-level workers:customfields permission. Use listcustom_fields to find valid IDs.

archive_custom_field

Archive a custom worker field. Archived fields keep their existing worker values but cannot receive new ones. Use listcustomfields to find valid IDs. Requires the manage-level workers:custom_fields permission.

create_field_option

Add an option to a select or multiselect custom worker field. The option value should be treated as stable; the label can change. Use listcustom_fields to find the field ID.

update_field_option

Update the label or sort order of a custom worker field option. Options of archived fields cannot be edited. Use getcustomfield on the parent field to find valid option IDs.

delete_field_option

Delete a custom worker field option that is not applied to any worker. Options in use must be archived instead using archivefieldoption. Use getcustomfield on the parent field to find valid option IDs.

archive_field_option

Archive a custom worker field option. Archived options remain on existing worker values but cannot be newly selected. Use getcustomfield on the parent field to find valid option IDs.

list_custom_field_values

List custom field values for workers, optionally filtered by worker or field. Values are returned only for fields whose category your API key can read. Use listworkers for workerIds and listcustomfields for fieldIds. Pass workerids or field_ids to limit the response size — without filters this returns every value for every worker, which can be very large.

set_custom_field_value

Create or replace a worker's value for a custom field (upsert). The value shape must match the field type. Use listworkers for the worker ID and getcustomfield for the field ID and, for select/multiselect fields, valid option IDs.

clear_custom_field_value

Remove a worker's value for a custom field. Use listworkers for the worker ID and listcustom_fields for the field ID.

list_departments

List all departments for your company, with cursor pagination. Use this to find departmentId values for createemployee, createcontractor, and create_offer.

create_department

Create a new department for your company.

update_department

Update an existing department's name. Use list_departments to find valid IDs.

list_levels

List the active standard job levels available to your company. Use this to find levelid values (jlvl...) for createemployee, createcontractor, createoffer, and updateworker. Returns enabled=false and an empty list when job levels are not enabled.

list_offers

List candidate offers. Supports filtering by status, worker type, and candidate email, plus cursor pagination. Use this to find offer IDs for voidoffer, extendofferdeadline, and resendoffer.

create_offer

Create and send a candidate offer. The candidate receives an email with a link to the offer portal, so only call this once you are ready to make the offer. Use listdepartments for departmentId and listworkers for managerId. position.country is required when workertype is globalcontractor. Optional levelid: use listlevels.

void_offer

Void a previously sent offer, giving a voidreason ('candidatedeclined' or 'other'). Only offers in 'sent' status can be voided. Use list_offers to find valid offer IDs.

extend_offer_deadline

Extend the expiration deadline of a sent offer. Use list_offers to find valid offer IDs.

resend_offer

Resend the offer email to the candidate for a sent offer. Use list_offers to find valid offer IDs.

list_pay_rates

List pay rates visible to the API key. Filter by workerid (use listworkers), effective date range, or regular/additional type. US and global worker rates require their corresponding compensation read scope.

get_pay_rate

Get a specific pay rate by ID. The API key must have the compensation read scope corresponding to the worker. Use listpayrates to find valid IDs.

create_regular_pay_rate

Create an effective-dated regular pay rate for a worker (use listworkers for the ID). amount is in minor units and required unless type is 'variable'; hourly rates need requirehourssubmission. A same-date rate replaces a future rate; one on another date blocks creation, so delete it first. Needs workers:us:compensation|write or workers:global:compensation|write. Undo: deleteregularpayrate.

delete_regular_pay_rate

Delete a worker's future regular pay rate or variable-pay boundary by workerid and effectivedate (after today, UTC). The previous rate then extends through the deleted range. Find fixed rates with listpayrates; variable boundaries have no row, so use the date you created. No update exists: create a same-date replacement.

list_paychecks

List per-worker paycheck summaries newest first. By default includes every worker type visible to the API key (US W-2 employees, US 1099 contractors, and global contractors). Filter by payrollids (use listpayrolls), workerids (use listworkers), workertypes, payrolltypes, statuses, paymentmethods, compensationcurrencies, pay_frequencies, or a payday date range. Max 50 per call.

get_paycheck

Get a paycheck by ID, including its earnings, reimbursements, deductions, benefits, and tax line items. All worker types use the same schema; categories that don't apply to a worker are zero-valued or empty. Use list_paychecks to find valid IDs.

list_payrolls

List payroll run summaries newest first. Every amount in totals is expressed in fundingcurrency. Filter by types, subtypes, statuses, payfrequencies, a payday date range, or a pay period end date range. Max 50 per call.

get_payroll

Get a payroll run by ID, including its funding method, reopen deadline, and approval timestamp. Every amount in totals is expressed in fundingcurrency. Use listpayrolls to find valid IDs.

list_time_off_policies

List the time off policies for your company, with cursor pagination.

get_time_off_policy

Get a specific time off policy by ID. Use listtimeoff_policies to find valid IDs.

list_time_off_assignments

List time off assignments (mappings between workers and time off policies). Useful for finding which policies a worker is assigned to, or which workers are assigned to a given policy. Filter by policyIds (use listtimeoffpolicies) or workerIds (use listworkers).

list_time_off_balances

Get worker remaining time-off balances. Filter by policyIds (use listtimeoffpolicies), workerIds (use listworkers), and a start/end date range.

list_time_off_requests

Get the time off requests that workers in your company have made. Filter by status, policyIds (use listtimeoffpolicies), workerIds (use listworkers), and start/end date ranges.

validate_credential

Validate Warp credentials by making a test API call. Returns success status and message. Use this to verify the API key is valid.

list_workers

List workers (employees and contractors). Supports filtering by status, type, and work email, plus cursor pagination. Omits DOB, address, pay and custom fields (previously always returned) unless includedetails is true. Use this to find worker IDs for getworker, updateworker, inviteworker, deleteworker, and as managerId in createemployee/create_contractor.

get_worker

Get a specific worker by ID. Use list_workers to find valid worker IDs.

create_employee

Create a new US employee in draft status. Requires a valid departmentId (use listdepartments) and managerId (use listworkers). Set workLocation to an office (with a workplaceId from listworkplaces) or remote (with a US state). The worker must be invited separately via inviteworker before they can complete onboarding. Optional levelid: use listlevels.

create_contractor

Create a new contractor (individual or business) in draft status. Requires a valid departmentId (use listdepartments) and managerId (use listworkers). businessName is required when entitytype is 'business'. The worker must be invited separately via inviteworker before they can complete onboarding. Optional levelid: use listlevels.

update_worker

Update a worker's profile, contact details, address, position, department (use listdepartments), manager (use listworkers), start date, or workplace (use listworkplaces). Null fields are left unchanged; list fields in clearfields to unset them. Contact email can change only for draft or invited workers. Optional levelid: use listlevels.

invite_worker

Send or resend the onboarding invite email to a worker so they can accept and complete onboarding to Warp. If already invited, the invite is resent with extended validity. Returns the updated worker. Use list_workers to find the worker ID.

delete_worker

Delete a worker. Only workers who have not yet completed onboarding (draft, invited, or onboarding status) can be deleted; active workers must be offboarded instead. Use list_workers to find the worker ID and check its status.

list_workplaces

List all workplaces for your company, with cursor pagination. Use this to find workplaceId values for the office variant of workLocation in create_employee.

create_workplace

Create a new workplace for your company.

update_workplace

Update an existing workplace's name. Use list_workplaces to find valid IDs.

View all tools by creating a free account See more tools

How to set up Merge Agent Handler

In an mcp.json file, add the configuration below, and restart Cursor.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5      "headers": {
6        "Authorization": "Bearer yMt*****"
7      }
8    }
9  }
10}
11

Copy Code

Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.

Make sure Claude is using the Node v20+.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "command": "npx",
5      "args": [
6        "-y",
7        "mcp-remote@latest",
8        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9        "--header",
10        "Authorization: Bearer ${AUTH_TOKEN}"
11      ],
12      "env": {
13        "AUTH_TOKEN": "yMt*****"
14      }
15    }
16  }
17}

Copy Code

Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.

Learn more in the official documentation ↗

1{
2    "mcpServers": {
3      "agent-handler": {
4        "command": "npx",
5        "args": [
6          "-y",
7          "mcp-remote@latest",
8          "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9          "--header",
10          "Authorization: Bearer ${AUTH_TOKEN}"
11        ],
12        "env": {
13          "AUTH_TOKEN": "<ah-production-access-key>"
14        }
15      }
16    }
17  }

Copy Code

In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".

You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.

Learn more in the official documentation ↗

1{
2  "inputs": [
3    {
4      "type": "promptString",
5      "id": "agent-handler-auth",
6      "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7      "password": true
8    }
9  ],
10  "servers": {
11    "agent-handler": {
12      "type": "stdio",
13      "command": "npx",
14      "args": [
15        "-y",
16        "mcp-remote@latest",
17        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18        "--header",
19        "Authorization: Bearer ${input:agent-handler-auth}"
20      ]
21    }
22  }
23}