MCP server - Golden Suite

GoldenMatch provides an MCP (Model Context Protocol) server for integration with Claude Desktop, Claude Code, and other MCP-compatible AI assistants. 85 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, Identity Graph tools, and document-extraction 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/"
        }
    }
}

Or browse on Smithery: 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.
{ "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:

{ "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 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

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

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 for the full variable reference. Or add to your Claude Desktop configuration (claude_desktop_config.json):

{
    "mcpServers": {
        "goldenmatch": {
            "command": "goldenmatch",
            "args": ["mcp-serve", "--file", "customers.csv"]
        }
    }
}

With a config file:

{
    "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.

"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).

"Find duplicates of John Smith"

get_cluster

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

"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).

"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).

"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"

run_transforms

Normalize phone numbers (E.164), dates (ISO), categorical spelling, and Unicode. Requires 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. 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.

"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"

More base tools (introspection, scoring, I/O)

Beyond the sections above, the base surface exposes these tools. They round out the 39 base tools and are mostly leaf primitives an agent composes.

Tool	Behavior
`list_clusters`	List duplicate clusters: cluster IDs, sizes, and member counts.
`get_golden_record`	Get the merged golden (canonical) record for a cluster.
`shatter_cluster`	Break an entire cluster into individual records.
`profile_data`	Data-quality profile: column types, null rates, unique counts, sample values. (Also the target of the `profile` alias.)
`review_config`	Run the config healer over the loaded dataset and report recommended fixes.
`config_weaknesses`	Diagnose weaknesses in the loaded run’s config.
`convert_splink_config`	Convert a Splink settings JSON (bare or trained) into a GoldenMatch config.
`export_results`	Export matching results to a file (CSV or JSON).
`write_csv`	Write a list of record objects to a CSV file.
`read_file`	Read a CSV/JSON file and return the first N records.
`score_strings`	Score similarity between two strings with the requested scorer.
`score_pair`	Score two record objects across weighted fields; returns a combined score.
`find_exact_matches`	Find exact matches on a field in a file; returns pairs.
`find_fuzzy_matches`	Find fuzzy matches in a block of rows; returns scored pairs.
`build_clusters`	Group records into clusters given a file and matchkey definition.
`list_scorers`	List all available similarity scorers.
`list_transforms`	List all available field transforms.
`list_strategies`	List all golden-record survivorship strategies.
`list_blocking_strategies`	List all blocking strategy names.
`server_info`	Return metadata about this GoldenMatch MCP server.

Document extraction tools

Two tools extract structured records from unstructured documents (PDF / image). See Documents.

Tool	Behavior
`documents_suggest_schema`	Propose a target extraction schema (JSON) from a sample document image/PDF.
`documents_ingest`	Extract records from documents (PDF/image) against a target schema.

In addition, 19 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, upload_dataset). See ER 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:

{
  "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 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:

“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.”

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 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 85 distinct tools reconcile as: 19 agent-level + 7 Learning Memory + 15 Identity Graph + 3 routing + 39 base data/inspection + 2 document-extraction 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 90. 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:

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

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.

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

​Remote vs. Local

​Remote Server (no install required)

​Using local files with the remote server

​Local Server

​Start the server

​Authentication (HTTP transport)

​Path sandbox

​Tools

​get_stats

​find_duplicates

​get_cluster

​match_record

​explain_match

​unmerge_record

​suggest_config

​list_domains

​create_domain

​test_domain

​pprl_auto_config

​pprl_link

​scan_quality

​fix_quality

​run_transforms

​evaluate

​analyze_blocking

​compare_clusters

​schema_match

​lineage

​list_runs

​rollback

​More base tools (introspection, scoring, I/O)

​Document extraction tools

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

​Learning Memory tools (v1.6.0)

​Identity Graph tools (v2.0)

​Routing tools

​Tool count breakdown

​How it works

​Example conversation

​Auto-config mode

​See also

Remote vs. Local

Remote Server (no install required)

Using local files with the remote server

Local Server

Start the server

Authentication (HTTP transport)

Path sandbox

Tools

get_stats

find_duplicates

get_cluster

match_record

explain_match

unmerge_record

suggest_config

list_domains

create_domain

test_domain

pprl_auto_config

pprl_link

scan_quality

fix_quality

run_transforms

evaluate

analyze_blocking

compare_clusters

schema_match

lineage

list_runs

rollback

More base tools (introspection, scoring, I/O)

Document extraction tools

AutoConfigController telemetry (v1.7-v1.12)

Learning Memory tools (v1.6.0)

Identity Graph tools (v2.0)

Routing tools

Tool count breakdown

How it works

Example conversation

Auto-config mode

See also