MCP: expose record merge as a tool (mergeCompanies/mergePeople already exist in GraphQL)

[xgp]

Summary

There is no merge tool anywhere in the MCP surface, so an agent that creates a duplicate cannot repair it. The capability already exists — mergeCompanies and mergePeople are GraphQL mutations, and merge is available in the UI — it is simply not exposed as a tool.

The bundled crm-hygiene skill acknowledges the gap and routes around it:

You cannot merge records. There is no merge tool; merging happens in the UI, where the user selects the records and uses the Merge action. Report each duplicate pair with both records referenced and leave the merge to them.

So the agent-facing story for the one operation that fixes duplicates is "ask a human to go and do it".

Why this matters more than a typical missing tool

Duplicate prevention is only partial, which makes repair load-bearing:

• The database enforces a unique constraint on the company domain, so a second record on the same domain is blocked.
• Name duplicates are not blocked. On a stock workspace I created Harbour Point IT on harbourpoint.example and Harbour Point I.T. Ltd on harbourpoint.co.example, plus a third with the same name and no domain. All three persisted.
• That is the realistic duplicate: the same company found twice under two domains, or found before its domain is known. duplicateCriteria on company is [["name"], ["domainNamePrimaryLinkUrl"]], so the product already considers a name collision a duplicate — it just does not act on it.

An agent doing research at any volume will create these. Today the only defence is its own discipline in searching before every create, and the only remedy is a human in the UI. Worse, the duplicate-blocking that does work surfaces as a raw constraint name:

A duplicate entry was detected: unique constraint company.IDX_UNIQUE_2a32339058d0b6910b0834ddf81 was violated

which does not say which record was collided with, so the agent still has to search to recover the existing id.

What already works

mergeCompanies behaves exactly as an agent would want, including a dry run. Verified against a real pair of duplicates:

mutation($ids: [ID!]!, $i: Int, $d: Boolean) {
  mergeCompanies(ids: $ids, conflictPriorityIndex: $i, dryRun: $d) {
    id name priority researchStatus staffEstimate googleWorkspace
  }
}

• dryRun: true returns the merged shape and writes nothing (both records still present afterwards).
• Non-conflicting fields union across the records.
• conflictPriorityIndex selects which record wins a conflict.
• On a real merge, relations follow: related custom-object records, people and note targets all ended up on the surviving record, and the losing record was soft-deleted.

That is a well-behaved, previewable, reversible operation — precisely the kind of thing that is safe to give an agent.

Request

Expose merge as an MCP tool, e.g. merge_records / merge_companies / merge_people, with ids, conflictPriorityIndex and dryRun passed through.

Two things that would make it materially more useful to an agent:

1. Keep dryRun in the tool surface. It lets an agent show the user exactly what a merge would produce before asking for approval, which is what crm-hygiene already asks for ("Always confirm before writing. Show what you will change and wait.").
2. Consider custom objects. Merge currently exists only for companies and people; there is no mergeEvidences or equivalent for a custom object. Anyone modelling their own entities hits the same wall one level down.

A smaller, independent improvement: have the unique-constraint violation name the conflicting record id, so an agent can recover from a failed create in one step instead of a follow-up search.

Environment

• Self-hosted, twentycrm/twenty:latest, image digest sha256:c6fcea05fc7302a4e620bc1556493abf9b919e62d808c155fedc19a798bf5578 (created 2026-09-24), Postgres 16
• MCP over streamable HTTP with an API key; 313 tools in the catalog, none matching merge

[twenty-eng-sync[bot]]

This is not a crash/regression but a missing agent capability: MCP exposes no tool for record merge, even though mergeCompanies/mergePeople already exist as GraphQL mutations and the UI provides Merge. Severity MEDIUM because it blocks automated duplicate repair (core agent workflow) but is partially workaroundable via manual UI merge. Likely missing MCP tool wiring in backend MCP/tool registry layer (no code located within fetch budget). Report is clear on behavior and request; missing only: exact MCP server/tool catalog code location, and whether any existing internal merge tool endpoints exist but are not exposed.

[xgp]

I encountered this when having multiple agents doing market research at the same time. The inability to allow the agents to identify and resolve duplicates by merging was a blocker. Given the necessity of the use case, I added a local skill with the following script that does it through the GraphQL interface. This unblocked me and the agents, but it seems like this should be a method exposed to the MCP server.

#!/usr/bin/env bash
# Merge duplicate CRM records through Twenty's GraphQL API.
#
# The MCP surface has no merge tool (twentyhq/twenty#26746), but `mergeCompanies`
# and `mergePeople` exist as GraphQL mutations. This is the interim path.
#
#   merge.sh company --dry-run <keep-id> <loser-id> [<loser-id>...]
#   merge.sh company            <keep-id> <loser-id> [<loser-id>...]
#   merge.sh person  --dry-run  <keep-id> <loser-id>
#
# The FIRST id is the record that wins field conflicts; the others are merged into
# it and soft-deleted. Non-conflicting fields union across all of them, and
# relations (evidence, contacts, notes, tasks) follow to the survivor.
#
# ALWAYS run --dry-run first and show the result before merging for real.
#
# Env: TWENTY_URL (default http://localhost:3001), TWENTY_API_KEY (required).

set -euo pipefail

URL="${TWENTY_URL:-http://localhost:3001}"
KEY="${TWENTY_API_KEY:?TWENTY_API_KEY is not set — take it from the private MCP client config, never from this repo}"

OBJ="${1:?usage: merge.sh <company|person> [--dry-run] <keep-id> <loser-id>...}"; shift
DRY=false
if [[ "${1:-}" == "--dry-run" ]]; then DRY=true; shift; fi

case "$OBJ" in
  company) MUTATION=mergeCompanies
           FIELDS='id name priority researchStatus managedClientsEstimate staffEstimate hqCountry designPartnerValue lastResearchedAt domainName{primaryLinkUrl}' ;;
  person)  MUTATION=mergePeople
           FIELDS='id name{firstName lastName} jobTitle contactRole contactDetailPublishedBy suppressed' ;;
  *) echo "merge.sh: only 'company' and 'person' support merge; '$OBJ' does not (see twentyhq/twenty#26746)" >&2; exit 2 ;;
esac

[[ $# -ge 2 ]] || { echo "merge.sh: need a keep-id and at least one loser-id" >&2; exit 2; }

# The winning record is the FIRST id, so conflictPriorityIndex is 0.
IDS=$(printf '%s\n' "$@" | python3 -c 'import json,sys; print(json.dumps([l.strip() for l in sys.stdin if l.strip()]))')

python3 - "$URL" "$KEY" "$MUTATION" "$FIELDS" "$IDS" "$DRY" <<'PY'
import json, sys, urllib.request, urllib.error
url, key, mutation, fields, ids, dry = sys.argv[1:7]
ids = json.loads(ids)
query = (f'mutation($ids:[ID!]!,$i:Int,$d:Boolean){{ {mutation}'
         f'(ids:$ids,conflictPriorityIndex:$i,dryRun:$d){{ {fields} }} }}')
req = urllib.request.Request(
    f'{url}/graphql',
    data=json.dumps({'query': query,
                     'variables': {'ids': ids, 'i': 0, 'd': dry == 'true'}}).encode(),
    headers={'Authorization': f'Bearer {key}', 'Content-Type': 'application/json'})
try:
    res = json.loads(urllib.request.urlopen(req).read().decode())
except urllib.error.HTTPError as e:
    res = json.loads(e.read().decode())
if res.get('errors'):
    print('MERGE FAILED:', json.dumps(res['errors'], indent=2)); sys.exit(1)
print(('DRY RUN — nothing was written' if dry == 'true' else 'MERGED'),
      f'({len(ids)} records, keeping {ids[0]})')
print(json.dumps(res['data'][mutation], indent=2))
if dry == 'true':
    print('\nRe-run without --dry-run to apply.')
PY