Connect your AI Agents to Warp in minutes
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.
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.
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_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.
void_offer
Void a previously sent offer. 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.
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. Use this to find worker IDs for getworker, 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.
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.
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. 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.
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}
11Open 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}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 }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}FAQs on using Merge's Warp MCP server
FAQs on using Merge's Warp MCP server
Ready to try it out?
Whether you're an engineer experimenting with agents or a product manager looking to add tools, you can get started for free now
