> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bensevern.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Connect GoldenMatch to Claude Desktop, Claude Code, and other MCP clients — 82 tools for autonomous entity resolution, data inspection, Learning Memory, and Identity Graph.

GoldenMatch provides an MCP (Model Context Protocol) server for integration with Claude Desktop, Claude Code, and other MCP-compatible AI assistants. 82 tools total, spanning agent-level tools for autonomous ER, data tools for inspection and management, config-suggestion and PPRL tools, Learning Memory tools for persisting steward decisions, and Identity Graph tools.

<Tip>
  Looking for AI-to-AI autonomy? See the [ER Agent (A2A)](/docs/goldenmatch/agent) page for agent framework integration (LangChain, CrewAI, AutoGen).
</Tip>

## Remote vs. Local

|          | Remote (Smithery) | Local                          |
| -------- | ----------------- | ------------------------------ |
| Install  | None              | `pip install goldenmatch[mcp]` |
| Latency  | \~200ms (network) | \<10ms                         |
| Data     | Upload to server  | Stays on your machine          |
| Best for | Quick exploration | Production, private data       |

## Remote Server (no install required)

GoldenMatch is available as a hosted remote MCP server on Smithery. Connect from Claude Desktop, Claude Code, or any MCP client without installing anything locally.

Add to your `claude_desktop_config.json`:

```json theme={null}
{
    "mcpServers": {
        "goldenmatch": {
            "url": "https://goldenmatch-mcp-production.up.railway.app/mcp/"
        }
    }
}
```

Or browse on Smithery: [https://smithery.ai/servers/benzsevern/goldenmatch](https://smithery.ai/servers/benzsevern/goldenmatch)

### Using local files with the remote server

The hosted server resolves `file_path` on the **server's** filesystem, so your local paths (`C:\Users\...`, `/home/...`) aren't visible to it. Feed it a local file two ways, neither of which hosts your data anywhere:

* **Inline `file_content`** — every file-taking tool (`analyze_data`, `auto_configure`, `agent_deduplicate`, `scan_quality`, `schema_match`, `pprl_link`, ...) accepts `file_content` as an alternative to `file_path`. Send it base64-encoded (default), or set `encoding: "text"` for raw text (e.g. CSV/JSON). The server writes it to a temp file and runs the tool on it.

  ```json theme={null}
  {
    "name": "analyze_data",
    "arguments": { "file_content": "<base64 of your CSV>", "filename": "customers.csv" }
  }
  ```

* **`upload_dataset`** — upload the bytes once and reuse the returned server path across many calls:

  ```json theme={null}
  { "name": "upload_dataset", "arguments": { "file_content": "<base64>", "filename": "customers.csv" } }
  // -> { "path": "/data/goldenmatch-uploads/<id>-customers.csv", "bytes": 8369635, "filename": "customers.csv" }
  ```

  Pass that `path` as `file_path` to `analyze_data`, `agent_deduplicate`, etc.

Uploads are ephemeral scratch: capped at 64 MB (`GOLDENMATCH_MCP_MAX_UPLOAD_BYTES`), reaped after 24 h (`GOLDENMATCH_MCP_UPLOAD_TTL`), and written under the server's `GOLDENMATCH_ALLOWED_ROOT` so the [path sandbox](#path-sandbox) still applies. For datasets larger than the cap, pass a public `http(s)://` URL as `file_path` — the server reads those directly.

## Local Server

### Start the server

```bash theme={null}
pip install goldenmatch[mcp]
goldenmatch mcp-serve --file customers.csv --config config.yaml
# Or with HTTP transport:
goldenmatch mcp-serve --file customers.csv --transport http --port 8200
```

### Authentication (HTTP transport)

The HTTP server is fail-closed: binding to a non-loopback host (the default is
`0.0.0.0`) refuses to start unless `GOLDENMATCH_MCP_TOKEN` is set. When the
token is set, every request to `/mcp` must carry it as a bearer token. The
`/.well-known/mcp/server-card.json` healthcheck stays public.

```bash theme={null}
# Exposed bind: token required, enforced on /mcp
export GOLDENMATCH_MCP_TOKEN="your-secret-token"
goldenmatch mcp-serve --transport http --port 8200

curl -H "Authorization: Bearer your-secret-token" http://host:8200/mcp/
```

<Info>
  Local development on loopback runs token-free:
  `goldenmatch mcp-serve --transport http --host 127.0.0.1`. The stdio transport
  (Claude Desktop) is local-only and never requires a token.
</Info>

### Path sandbox

For deployed or shared MCP servers, set `GOLDENMATCH_ALLOWED_ROOT` to
restrict every user-supplied file path to a specific directory tree. Any
path that resolves outside that root returns `{"error": "..."}` from the
tool rather than raising an unhandled exception.

```bash theme={null}
# Railway / Docker: scope MCP tools to the /data volume
export GOLDENMATCH_ALLOWED_ROOT=/data
goldenmatch mcp-serve --transport http --port 8200
```

Unset (the default) means no containment -- any path accessible to the
server process is valid. This is the correct default for local stdio
usage (Claude Desktop). See [Configuration](/docs/goldenmatch/configuration#path-sandbox)
for the full variable reference.

Or add to your Claude Desktop configuration (`claude_desktop_config.json`):

```json theme={null}
{
    "mcpServers": {
        "goldenmatch": {
            "command": "goldenmatch",
            "args": ["mcp-serve", "--file", "customers.csv"]
        }
    }
}
```

With a config file:

```json theme={null}
{
    "mcpServers": {
        "goldenmatch": {
            "command": "goldenmatch",
            "args": ["mcp-serve", "--file", "customers.csv", "--config", "config.yaml"]
        }
    }
}
```

## Tools

The MCP server exposes the following tools to Claude Desktop:

### get\_stats

Get dataset statistics: record count, cluster count, match rate, cluster sizes.

```text theme={null}
"How many duplicates did you find?"
```

### find\_duplicates

Search for duplicate records matching a query.

*Also answers to `dedupe` (the TypeScript server's name for this operation).*

```text theme={null}
"Find duplicates of John Smith"
```

### get\_cluster

Get details of a specific cluster including all member records and pair scores.

```text theme={null}
"Show me cluster 42"
```

### match\_record

Match a new record against the loaded dataset.

*Also answers to `match` (the TypeScript server's name for this operation).*

```text theme={null}
"Does this record match anything: name=Jane Doe, email=jane@example.com?"
```

### explain\_match

Explain why two specific records were matched or not matched.

*Also answers to `explain_pair` (the TypeScript server's name for this operation).*

```text theme={null}
"Why were records 42 and 108 matched?"
```

### unmerge\_record

Remove a record from its cluster. Re-clusters the remaining members.

```text theme={null}
"Remove record 215 from its cluster, it was a false match"
```

### suggest\_config

Analyze bad merges, identify which fields caused false matches, and suggest threshold/weight changes.

```text theme={null}
"Cluster 5 has a bad merge. What should I change?"
```

### list\_domains

List all available domain packs (built-in and custom).

```text theme={null}
"What domain packs are available?"
```

### create\_domain

Create a new custom domain pack.

```text theme={null}
"Create a domain pack for automotive parts with fields: part_number, manufacturer, fitment"
```

### test\_domain

Test a domain pack against sample data to verify extraction quality.

```text theme={null}
"Test the electronics domain pack on my data"
```

### pprl\_auto\_config

Analyze data and recommend optimal PPRL parameters.

```text theme={null}
"What PPRL settings should I use for this dataset?"
```

### pprl\_link

Run privacy-preserving record linkage.

```text theme={null}
"Link hospital_a.csv and hospital_b.csv using PPRL"
```

### scan\_quality

Scan data for quality issues (encoding errors, Unicode problems, format violations) without applying fixes. Requires `pip install goldenmatch[quality]`.

```text theme={null}
"Scan my data for quality issues before matching"
```

### fix\_quality

Scan and apply data quality fixes (safe or moderate mode). Optionally saves the fixed CSV.

```text theme={null}
"Fix encoding issues in customers.csv using moderate mode"
```

### run\_transforms

Normalize phone numbers (E.164), dates (ISO), categorical spelling, and Unicode. Requires `pip install goldenmatch[transform]`.

```text theme={null}
"Normalize the phone and date formats in my data"
```

### evaluate

Score the loaded run against ground-truth pairs: precision, recall, and F1.

```text theme={null}
"How accurate is this matching against my labeled pairs in gt.csv?"
```

### analyze\_blocking

Diagnose blocking on the loaded dataset: ranked key candidates with block counts, max block size, candidate-pair totals, and estimated recall.

```text theme={null}
"Why is matching producing so many candidate pairs?"
```

### compare\_clusters

Compare two ER clustering outcomes without ground truth (CCMS): unchanged / merged / partitioned / overlapping, plus the Talburt-Wang Index. Takes two cluster JSON files.

```text theme={null}
"How did clustering change between the old run and the new one?"
```

### schema\_match

Auto-map columns between two files with different schemas (synonym + name similarity), with a confidence score per mapping.

```text theme={null}
"Map the columns between crm.csv and billing.csv before I match them"
```

### lineage

Field-level provenance for the loaded run: the per-field score breakdown behind each scored pair, plus cluster id. When the run's config uses survivorship `field_groups`, the result also includes a top-level `golden_records` section whose entries carry a `groups` array -- recording which columns were promoted together, the winning source record, and the strategy used.

```text theme={null}
"Show me the lineage for the pairs in cluster 14"
```

### list\_runs

List previous dedupe/match runs from the run log (for rollback).

```text theme={null}
"What runs can I roll back?"
```

### rollback

Undo a previous run by deleting its output files (looked up by run\_id). Destructive.

```text theme={null}
"Roll back run 2026-06-05-abc123"
```

In addition, 18 **agent-level tools** are available for autonomous operation (analyze\_data, auto\_configure, controller\_telemetry, agent\_deduplicate, agent\_match\_sources, agent\_explain\_pair, agent\_explain\_cluster, agent\_review\_queue, agent\_approve\_reject, agent\_compare\_strategies, suggest\_pprl, scan\_quality, fix\_quality, run\_transforms, sensitivity, incremental, certify\_recall, retrieve\_similar). See [ER Agent](/docs/goldenmatch/agent) for details.

### AutoConfigController telemetry (v1.7-v1.12)

`auto_configure` was rewired in PR #161 to invoke the v1.7+ AutoConfigController instead of the legacy `select_strategy` heuristic. It now returns:

```json theme={null}
{
  "config": { "...": "full GoldenMatchConfig" },
  "telemetry": {
    "available": true,
    "stop_reason": "green",
    "health": "green",
    "decisions": [],
    "column_priors": [],
    "committed_matchkeys": [],
    "negative_evidence": []
  }
}
```

`agent_deduplicate` and `agent_match_sources` both include a `telemetry` field in their result dict so the host LLM can see `stop_reason`, refit decisions, and Path Y negative-evidence without a second call.

The standalone `controller_telemetry` tool surfaces a per-session limitation note (MCP dispatch is stateless, so it can't recall a prior call's telemetry — use the inline telemetry from `auto_configure` / `agent_deduplicate` instead).

### Learning Memory tools (v1.6.0)

Seven tools surface the persistent corrections store. See [Learning Memory](/docs/goldenmatch/learning-memory) for the full feature.

| Tool               | Behavior                                                                                         |
| ------------------ | ------------------------------------------------------------------------------------------------ |
| `list_corrections` | Page through stored corrections, optionally filtered by dataset and source.                      |
| `add_correction`   | Writes a correction with caller-supplied trust (`steward`/`unmerge` 1.0, `agent`/`llm` 0.5).     |
| `learn_thresholds` | Runs `MemoryLearner.learn()`; returns the adjustment dict per matchkey.                          |
| `memory_stats`     | Counts plus last-learned timestamps.                                                             |
| `memory_export`    | Returns all corrections as a JSON array (use server-side for review portability).                |
| `memory_import`    | Upserts corrections from a list of dicts (the shape `memory_export` returns); higher trust wins. |
| `list_plugins`     | List registered Learning Memory plugins/adapters available to the store.                         |

Natural-language workflow:

<Note>
  "Show me uncertain pairs from the last goldenmatch run on customers.csv, then mark rows 17 and 23 as not-a-match because they have different EINs."
</Note>

The host LLM calls `list_corrections` -> `add_correction` -> `learn_thresholds`.

### Identity Graph tools (v2.0)

Fifteen tools expose the durable identity layer above run-local clusters. See [Identity Graph](/docs/goldenmatch/identity-graph) for the full feature.

| Tool                        | Behavior                                                                      |
| --------------------------- | ----------------------------------------------------------------------------- |
| `identity_resolve`          | Resolve a record\_id to its durable identity (members, edges, recent events). |
| `identity_show`             | Full detail of one identity by entity\_id.                                    |
| `identity_list`             | List identities, optionally filtered by dataset/status.                       |
| `identity_history`          | Temporal event log for an identity (merges, splits, absorbs).                 |
| `identity_conflicts`        | Evidence edges marked `conflicts_with` for steward review.                    |
| `identity_merge`            | Manually merge two identities.                                                |
| `identity_split`            | Split records off an identity into a new identity.                            |
| `identity_claim`            | Claim/assign a record to a specific durable identity.                         |
| `identity_resolve_conflict` | Resolve a flagged `conflicts_with` edge.                                      |
| `identity_profile`          | Aggregate profile view across an identity's members.                          |
| `identity_stats`            | Counts and health metrics for the identity store.                             |
| `identity_worklist`         | Steward worklist of identities needing review.                                |
| `identity_audit`            | Audit-log entries for identity mutations.                                     |
| `identity_audit_seal`       | Seal the audit log (tamper-evident checkpoint).                               |
| `identity_audit_verify`     | Verify the audit log seal chain.                                              |

### Routing tools

Three tools plan and validate distributed execution routing for a run.

| Tool              | Behavior                                                               |
| ----------------- | ---------------------------------------------------------------------- |
| `plan_routing`    | Produce the per-stage distributed execution plan for a dataset/config. |
| `lint_routing`    | Lint a routing plan for misconfiguration or scale hazards.             |
| `explain_routing` | Explain why each stage was routed the way it was.                      |

### Tool count breakdown

The 69 distinct tools reconcile as: 18 agent-level + 7 Learning Memory + 15 Identity Graph + 3 routing + 26 base data/inspection tools.

The server additionally advertises 5 cross-language naming aliases — `dedupe`, `match`, `explain_pair`, `profile`, and `explain_cluster` — alternate names that match the TypeScript server's tool names, so an agent trained against either server can call the other. They forward to the canonical handlers above (`find_duplicates`, `match_record`, `explain_match`, `profile_data`, `agent_explain_cluster`), bringing the advertised total to 74. The TypeScript server mirrors this: it also answers to the Python names (`find_duplicates`, `match_record`, `explain_match`, `profile_data`).

## How it works

When the MCP server starts, it:

1. Loads data from the specified file(s)
2. Loads or auto-generates a matching configuration
3. Runs the full matching pipeline
4. Caches results in memory
5. Exposes tools via the MCP protocol over stdio

The server uses the `MatchEngine` from `goldenmatch.tui.engine` (which has no Textual dependency) for matching operations.

## Example conversation

With Claude Desktop connected to the GoldenMatch MCP server:

**You:** "How many duplicates are in my customer data?"

**Claude:** Uses `get_stats` tool. "Your dataset has 5,000 records with 847 duplicate clusters. The match rate is 12%, meaning about 600 records are duplicates."

**You:** "Show me the biggest cluster"

**Claude:** Uses `get_cluster` tool. "Cluster 14 has 8 members. Here are the records: \[table of members with field values and pairwise scores]"

**You:** "Record 215 doesn't belong there, remove it"

**Claude:** Uses `unmerge_record` tool. "Done. Record 215 has been removed from cluster 14. The remaining 7 records have been re-clustered."

**You:** "The name matching is too aggressive. What should I change?"

**Claude:** Uses `suggest_config` tool. "The jaro\_winkler threshold for first\_name is 0.80, which is catching partial matches like 'John' and 'Jonathan'. I suggest raising it to 0.88 and adding a last\_name exact match as a secondary check."

## Auto-config mode

If no config file is specified, the MCP server auto-configures matching rules:

```bash theme={null}
goldenmatch mcp-serve --file customers.csv
```

Auto-config detects column types, assigns appropriate scorers, and picks a blocking strategy. The `suggest_config` tool can then help refine the auto-generated config based on observed results.

## See also

| Topic                         | Link                                        |
| ----------------------------- | ------------------------------------------- |
| AI-to-AI agent protocol (A2A) | [ER Agent](/docs/goldenmatch/agent)              |
| REST API for HTTP integration | [Python API](/docs/goldenmatch/python-api)       |
| Quick start with Python/CLI   | [Quick Start](/docs/goldenmatch/quickstart)      |
| Full configuration reference  | [Configuration](/docs/goldenmatch/configuration) |