GoldenMatch provides an MCP (Model Context Protocol) server for integration with Claude Desktop, Claude Code, and other MCP-compatible AI assistants. 54 tools total: 16 agent-level tools for autonomous ER, 24 data tools for inspection and management, 7 Learning Memory tools (v1.6.0) for persisting steward decisions, and 7 Identity Graph tools.
Looking for AI-to-AI autonomy? See the ER Agent (A2A) page for agent framework integration (LangChain, CrewAI, AutoGen). 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:
{
"mcpServers": {
"goldenmatch": {
"url": "https://goldenmatch-mcp-production.up.railway.app/mcp/"
}
}
}
Local Server
Start the server
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.
# 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/
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.
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.
# Railway / Docker: scope MCP tools to the /data volume
export GOLDENMATCH_ALLOWED_ROOT=/data
goldenmatch mcp-serve --transport http --port 8200
claude_desktop_config.json):
{
"mcpServers": {
"goldenmatch": {
"command": "goldenmatch",
"args": ["mcp-serve", "--file", "customers.csv"]
}
}
}
{
"mcpServers": {
"goldenmatch": {
"command": "goldenmatch",
"args": ["mcp-serve", "--file", "customers.csv", "--config", "config.yaml"]
}
}
}
get_stats
Get dataset statistics: record count, cluster count, match rate, cluster sizes.
"How many duplicates did you find?"
find_duplicates
Search for duplicate records matching a query.
"Find duplicates of John Smith"
get_cluster
Get details of a specific cluster including all member records and pair scores.
match_record
Match a new record against the loaded dataset.
"Does this record match anything: name=Jane Doe, email=jane@example.com?"
explain_match
Explain why two specific records were matched or not matched.
"Why were records 42 and 108 matched?"
unmerge_record
Remove a record from its cluster. Re-clusters the remaining members.
"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.
"Cluster 5 has a bad merge. What should I change?"
list_domains
List all available domain packs (built-in and custom).
"What domain packs are available?"
create_domain
Create a new custom domain pack.
"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.
"Test the electronics domain pack on my data"
pprl_auto_config
Analyze data and recommend optimal PPRL parameters.
"What PPRL settings should I use for this dataset?"
pprl_link
Run privacy-preserving record linkage.
"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].
"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.
"Fix encoding issues in customers.csv using moderate mode"
pip install goldenmatch[transform].
"Normalize the phone and date formats in my data"
evaluate
Score the loaded run against ground-truth pairs: precision, recall, and F1.
"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.
"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.
"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.
"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.
"Show me the lineage for the pairs in cluster 14"
list_runs
List previous dedupe/match runs from the run log (for rollback).
"What runs can I roll back?"
rollback
Undo a previous run by deleting its output files (looked up by run_id). Destructive.
"Roll back run 2026-06-05-abc123"
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:
{
"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).
Six tools surface the persistent corrections store. See 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. |
“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.”
list_corrections -> add_correction -> learn_thresholds.
Seven tools expose the durable identity layer above run-local clusters. See 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. |
How it works
When the MCP server starts, it:
- Loads data from the specified file(s)
- Loads or auto-generates a matching configuration
- Runs the full matching pipeline
- Caches results in memory
- 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:
goldenmatch mcp-serve --file customers.csv
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 |
| REST API for HTTP integration | Python API |
| Quick start with Python/CLI | Quick Start |
| Full configuration reference | Configuration |