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

Connect your AI Agents to Copper in minutes

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

Start building for free

Read docs

Copper

Learn more about Merge Agent Handler

Available tools

list_activities

Search activities, optionally scoped to one record with parent, e.g. {'id': 185332522, 'type': 'person'} — this is how you read a contact's history. Set fullresult true to get every match rather than the latest per record. Use listactivity_types to filter by type.

get_activity

Fetch one activity by ID, including its type, the record it belongs to and its text body. Use list_activities to find the ID.

create_activity

Log an activity (note, call, meeting) against a record. Copper requires a type, a parent and details. Call listactivitytypes first and pick a 'user' category type — 'system' types are read-only. Returns the created activity including its ID.

update_activity

Update a logged activity's text or date. Copper requires the type on every update even when unchanged — call listactivitytypes or get_activity to supply it. Only 'user' category activities can be updated.

delete_activity

Permanently delete a logged activity by ID. This cannot be undone. Only 'user' category activities can be deleted; Copper's own 'system' audit entries cannot. Use list_activities to find the ID.

bulk_create_activities

Log up to 10 activities in one call, each with a type, a parent and details. Call listactivitytypes first for valid 'user' category type IDs. Copper answers 200 even when individual records fail, so check the per-record entries.

list_companies

Search companies with server-side filters (name, email domains, assignee, contact type, tags, location, interaction, created- and modified-date ranges) and sorting. Use listcontacttypes and list_users to find filter IDs.

get_company

Fetch one company by ID, including address, websites, tags and custom fields. Use list_companies to find the ID.

create_company

Create a company. Only a name is required. emaildomain must be unique across the account or the call fails. Call listcontacttypes, listusers and listcustomfield_definitions first for valid IDs. Returns the created company including its ID.

update_company

Update a company by ID. Only the fields you supply change, but list fields such as websites and tags replace the existing list rather than appending. Use list_companies to find the ID.

delete_company

Permanently delete a company by ID. This cannot be undone and does not delete the people linked to it. Use listcompanies to find the ID. Copper answers 200 even when no such record existed, returning the same body either way, so isdeleted true is not proof the record was there — confirm with a get or list call first if that matters.

bulk_create_companies

Create up to 10 companies in one call. Copper answers 200 even when individual records fail, so check the per-record entries: a success carries an id, a failure carries a message. Email domains must be unique across the account.

bulk_update_companies

Update up to 10 companies in one call, each identified by companyid. Copper answers 200 even when individual records fail, so check the per-record entries. Use listcompanies to find IDs.

list_leads

Search leads with server-side filters (name, emails, company, status, source, assignee, tags, location and value ranges) and sorting. Use listleadstatuses, listcustomersources and list_users to find filter IDs. Fails if the Leads module is off for the account.

get_lead

Fetch one lead by ID, including email, company name, status, value and custom fields. Use list_leads to find the ID.

create_lead

Create a lead. Only a name is required. Call listleadstatuses, listcustomersources, listusers and listcustomfielddefinitions first for valid IDs. A lead carries a single email, not a list. Returns the created lead including its ID.

update_lead

Update a lead by ID — change its status, owner, value or details. Only the fields you supply change, but list fields such as tags replace the existing list. Use listleads for the ID and listlead_statuses for status IDs.

delete_lead

Permanently delete a lead by ID. This cannot be undone — to qualify a lead instead, use convertlead. Use listleads to find the ID.

convert_lead

Convert a qualified lead into a person, and optionally a company and an opportunity. The lead is consumed and can no longer be fetched. Copper honours opportunitydetails but decides the person and company itself, so always read personname and companyname off the result to see what it actually made. Pass companydetails.id to control the company. Use listpipelinestages for the pipeline IDs opportunity_details takes.

bulk_create_leads

Create up to 10 leads in one call. Copper answers 200 even when individual records fail, so check the per-record entries: a success carries an id, a failure carries a message.

bulk_update_leads

Update up to 10 leads in one call, each identified by leadid. Copper answers 200 even when individual records fail, so check the per-record entries. Use listleads to find IDs.

get_account

Fetch the Copper account this credential belongs to: its ID, name, timezone and which optional modules are enabled. Check settings.settingenableleads here before using any lead tool — the lead endpoints fail when it is false.

list_users

List the users in the Copper account. Call this first to get the user IDs that assigneeid takes on every create and update tool, and that the assigneeids filter takes on every list tool.

list_pipelines

List the opportunity pipelines in the account. Call this to get the pipelineid that createopportunity and updateopportunity take. Some plans return an empty list here even though pipelines exist: in that case read pipelineid off listpipelinestages, then get_pipeline for its details.

get_pipeline

Get one opportunity pipeline by ID, including its stages and whether it tracks revenue. Use this when listpipelines returns an empty list, which some plans do even though pipelines exist. Read pipelineid from listpipelinestages or from an opportunity.

list_pipeline_stages

List every opportunity pipeline stage in the account, each naming the pipeline it belongs to. Call this to get the pipelinestageid that createopportunity and updateopportunity take when moving a deal.

list_activity_types

List the activity types in the account, split into the 'user' types an integration may write and the read-only 'system' types Copper writes itself. Call this before createactivity or updateactivity and pick a user type.

list_contact_types

List the contact types in the account, e.g. 'Potential Customer'. Call this to get the contacttypeid that createperson, updateperson, createcompany and updatecompany take, and that the contacttypeids filter takes.

list_customer_sources

List the customer sources in the account, e.g. 'Cold Call'. Call this to get the customersourceid that createopportunity, updateopportunity, createlead and updatelead take.

list_loss_reasons

List the loss reasons in the account. Call this to get the lossreasonid to pass to update_opportunity when setting an opportunity's status to Lost.

list_lead_statuses

List the lead statuses in the account. Call this to get the statusid that createlead and updatelead take. Fails if the Leads module is off for the account — check getaccount first.

list_custom_field_definitions

List the custom field definitions configured on the account, with each field's data type, the entities it applies to, and its dropdown options. Call this to get the customfielddefinitionid every customfields value needs.

list_tags

List the tags already in use across the account. Call this before setting tags on a record so you reuse an existing tag instead of creating a near-duplicate.

list_opportunities

Search opportunities with server-side filters (pipeline, stage, status, priority, assignee, company, value, close-date and stage-change-date ranges) and sorting. Use listpipelinestages (it carries each stage's pipelineid) and listusers to find filter IDs; list_pipelines returns empty on some plans.

get_opportunity

Fetch one opportunity by ID, including pipeline, stage, value, status and custom fields. Use list_opportunities to find the ID.

create_opportunity

Create an opportunity. Copper requires a name and a primarycontactid — use listpeople or getpersonbyemail to get one. Call listpipelines and listpipeline_stages first to place it in a specific stage, or omit them to use the default pipeline. Returns the created opportunity including its ID.

update_opportunity

Update an opportunity by ID — move it to another stage, change its value, or close it by setting status to Won or Lost. Pair status 'Lost' with a lossreasonid from listlossreasons. Use listpipelinestages for stage IDs.

delete_opportunity

Permanently delete an opportunity by ID. This cannot be undone — to close a deal instead, use updateopportunity with status Won, Lost or Abandoned. Use listopportunities to find the ID.

bulk_create_opportunities

Create up to 10 opportunities in one call. Each needs a name and a primarycontactid. Copper answers 200 even when individual records fail, so check the per-record entries: a success carries an id, a failure a message.

list_people

Search people with server-side filters (name, emails, company, assignee, contact type, tags, location, interaction, created- and modified-date ranges) and sorting. Use this to browse or filter; use getpersonbyemail for an exact single lookup. Use listcontacttypes and listusers to find filter IDs.

get_person

Fetch one person by ID, including emails, phone numbers, company, tags and custom fields. Use listpeople or getpersonbyemail to find the ID.

get_person_by_email

Fetch one person by their exact email address. Use this when you have an email and need the person's ID; use list_people to browse or filter instead.

create_person

Create a person. Only a name is required. Call listcontacttypes, listusers, listcompanies and listcustomfielddefinitions first to get valid IDs for contacttypeid, assigneeid, company_id and custom fields. Returns the created person including its ID.

update_person

Update a person by ID. Only the fields you supply change; omitted fields are left alone, but list fields such as emails and tags replace the existing list rather than appending. Use list_people to find the ID.

delete_person

Permanently delete a person by ID. This cannot be undone. Use listpeople to find the ID and confirm the record before deleting. Copper answers 200 even when no such record existed, returning the same body either way, so isdeleted true is not proof the record was there — confirm with a get or list call first if that matters.

bulk_create_people

Create up to 10 people in one call. Copper answers 200 even when individual records fail, so check the per-record entries: a success carries an id, a failure carries a message. Email addresses must be unique across the account.

bulk_update_people

Update up to 10 people in one call, each identified by personid. Copper answers 200 even when individual records fail, so check the per-record entries. Use listpeople to find IDs.

list_projects

Search projects with server-side filters (name, assignee, status, tags and created/modified date ranges) and sorting. Use list_users to find assignee IDs.

get_project

Fetch one project by ID, including its assignee, status, tags and custom fields. Use list_projects to find the ID.

create_project

Create a project. Only a name is required. Set an owner with assigneeid from listusers, and use listcustomfield_definitions for custom field IDs. Returns the created project including its ID.

update_project

Update a project by ID — reassign it, rename it, or close it by setting status to Completed. Only the fields you supply change, but tags replace the existing list. Use list_projects to find the ID.

delete_project

Permanently delete a project by ID. This cannot be undone — to close a project instead, use updateproject with status Completed. Use listprojects to find the ID. Copper answers 200 even when no such record existed, returning the same body either way, so isdeleted true is not proof the record was there — confirm with a get or list_ call first if that matters.

list_related_items

List the records linked to one record — for example every opportunity and project attached to a person. Narrow with relatedentitytype (plural) to one kind of link. Use the matching list tool (listpeople, listcompanies) for entity_id.

relate_record

Link two existing records, e.g. attach an opportunity to a person. Both must already exist — this creates the link, not the records. relatedentitytype is singular here ('opportunity'), unlike listrelateditems. Use the matching list tools to find both IDs.

unrelate_record

Remove the link between two records. The records themselves are not deleted, only the relationship. relatedentitytype is singular here ('opportunity'). Use listrelateditems to confirm the link exists first.

list_tasks

Search tasks with server-side filters (assignee, status, priority, the project or opportunity a task hangs off, tags, and due/reminder/created/modified/completed date ranges) and sorting. Use listusers, listprojects and list_opportunities to find filter IDs.

get_task

Fetch one task by ID, including its assignee, status, due date and the record it is attached to. Use list_tasks to find the ID.

create_task

Create a task. Only a name is required. Attach it to a record with relatedresource, e.g. {'id': 185332522, 'type': 'person'}, and set an owner with assigneeid from list_users. Dates are Unix epoch seconds. Returns the created task including its ID.

update_task

Update a task by ID — reassign it, change its due date, or close it by setting status to Completed. Only the fields you supply change, but tags replace the existing list. Use list_tasks to find the ID.

delete_task

Permanently delete a task by ID. This cannot be undone — to close a task instead, use updatetask with status Completed. Use listtasks to find the ID. Copper answers 200 even when no such record existed, returning the same body either way, so isdeleted true is not proof the record was there — confirm with a get or list_ call first if that matters.

validate_credential

Validate Copper credentials by fetching the account. Returns success status and the account name. Requires both the API key and the email address of the user who generated it.

list_webhooks

List the webhook subscriptions registered on the account, each with the entity type and event it watches and the URL it posts to. Call this before creating one to avoid registering a duplicate.

get_webhook

Fetch one webhook subscription by ID, including its target URL, watched entity type and event. Use list_webhooks to find the ID.

create_webhook

Register a webhook subscription so Copper posts to your URL when a record changes. The target must already be a live HTTPS listener you control — Copper does not verify it and drops notifications to a dead URL. One subscription watches one entity type and one event.

update_webhook

Update a webhook subscription by ID: its target URL, secret, or customfieldcomputedvalues. Copper cannot change the entity type or event a subscription watches — it answers 200 and ignores them — so use deletewebhook and createwebhook for that. Use listwebhooks to find the ID.

delete_webhook

Delete a webhook subscription by ID. Copper stops posting notifications immediately. Use list_webhooks to find the ID.

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}