mcp-server-entity-enricher

# Entity Enricher MCP Server

[![MCP](https://img.shields.io/badge/MCP-remote%20server-blue)](https://modelcontextprotocol.io)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-ai.entityenricher%2Fenricher-blue)](https://registry.modelcontextprotocol.io)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Website](https://img.shields.io/badge/entityenricher.ai-docs-orange)](https://entityenricher.ai/docs/integrations/mcp)

A **hosted, remote [Model Context Protocol](https://modelcontextprotocol.io) server** for
[Entity Enricher](https://entityenricher.ai) — structured knowledge extraction with multiple
LLM providers. Connect Claude Desktop, Claude Code, Cursor, claude.ai or any MCP-compatible
client and, from inside a chat:

- **Author JSON schemas** — generate a sample entity, turn it into a schema, refine it in natural language.
- **Enrich entities** — single or batch (up to 100), against your schemas, with any of your configured models.
- **Enrich multilingually** — schemas with localized text fields get per-language values in every language you request, in one pass.
- **Fuse multi-model results** — conflicts detected field-by-field, resolved by voting or LLM arbitration.
- **Benchmark models on your own data** — saved scenarios, gold references, auto-scored quality / cost / speed.
- **Ground enrichments in documents** — upload PDFs, images or audio and attach them to any flow.

No install, no local process: the server runs at `https://entityenricher.ai/api/mcp/`
(streamable HTTP). This repository holds the public documentation and ready-to-use client
configs; the server implementation lives in the Entity Enricher platform.

Listed on the [official MCP Registry](https://registry.modelcontextprotocol.io) as
**`ai.entityenricher/enricher`** (see [server.json](server.json)).

## Quickstart

### Option 1 — OAuth (recommended)

For claude.ai, Claude Code, Cursor, and any MCP client that implements the standard OAuth
flow. **No API key to create or paste** — the client discovers the authorization server
automatically, your browser opens the Entity Enricher consent screen, and the connection acts
on your behalf with your own role. Revoke it anytime under **Settings → API Keys → Connected
Apps**.

<details open>
<summary><strong>Claude Code</strong></summary>

```bash
claude mcp add --transport http entity-enricher https://entityenricher.ai/api/mcp/
```

Then run `/mcp` in a session and pick **Authenticate** — your browser opens the consent page.
More options (project `.mcp.json`, API-key fallback): [examples/claude-code/](examples/claude-code/)
</details>

<details>
<summary><strong>claude.ai</strong></summary>

**Settings → Connectors → Add custom connector** with URL
`https://entityenricher.ai/api/mcp/`, then click **Authorize** on the consent screen.
Walkthrough: [examples/claude-ai-remote.md](examples/claude-ai-remote.md)
</details>

<details>
<summary><strong>Cursor / other OAuth-capable clients</strong></summary>

Register the URL with no headers and the client prompts you to sign in:
[examples/cursor/mcp.json](examples/cursor/mcp.json)
</details>

### Option 2 — API key (static JSON configuration)

For clients configured via a JSON file rather than an interactive sign-in (Claude Desktop,
Continue, Zed) — and for headless/CI use.

1. In the [Entity Enricher web UI](https://entityenricher.ai): **Settings → API Keys → New
   organization access key**. Pick a role — operator (read-mostly), editor (create/edit
   schemas), or owner (full control, required for benchmarks). Copy the `ent_…` value; it's
   only shown once.
2. For **Claude Desktop**, edit `~/Library/Application Support/Claude/claude_desktop_config.json`
   (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

   ```json
   {
     "mcpServers": {
       "entity-enricher": {
         "url": "https://entityenricher.ai/api/mcp/",
         "headers": { "X-API-Key": "ent_your_key_here" }
       }
     }
   }
   ```

   Restart Claude Desktop. Full file: [examples/claude-desktop/](examples/claude-desktop/)

### Try it

> List my Entity Enricher schemas, then enrich "Sanofi" against the pharmaceutical company
> schema in English and French.

Claude discovers the tools automatically, confirms the model and schema choice with you, and
returns the structured result inline.

## Recipes

Copy-paste chat walkthroughs of the three flows people ask about most:

| Recipe | What it covers |
|---|---|
| [Schema from sample](examples/recipes/schema-from-sample.md) | generate a sample → schema → refine → first enrichment |
| [Batch enrichment](examples/recipes/batch-enrichment.md) | entity lists, external APIs, async polling, partial-failure retry |
| [Model benchmark](examples/recipes/model-benchmark.md) | scenarios, gold references, auto-scored model comparison |

## Tools

<!-- TOOL_TABLE_START — generated by backend/scripts/generate_mcp_tool_table.py; do not edit by hand -->
**37 tools**, spanning the full schema-authoring and enrichment surface:

| Category | Tool | Description |
|---|---|---|
| Discovery | `list_models` | List the LLM models, languages, strategies, and (when the org has a plan with limits) the operational profile_limits available to the caller. |
| Schemas | `generate_sample` | Generate a realistic sample entity JSON from an entity-type description — the entry point of the schema-authoring loop. |
| Schemas | `list_schemas` | List saved JSON schemas in your organization, pinned ones first. |
| Schemas | `get_schema` | Fetch the full content of a saved schema by ID, including all properties, key fields, expertise domains, and validation rules. |
| Schemas | `create_schema_from_sample` | Generate and auto-save a JSON schema whose paths and types strictly follow an approved sample. |
| Schemas | `edit_schema` | Modify an existing saved schema using a natural-language prompt, via an LLM (e.g. 'add a regulatory_status field marked as a key property', 'remove the founding_year field', 'mark… |
| Schemas | `save_schema` | Persist a schema you authored directly (no LLM call, no cost) as a new saved schema. |
| Schemas | `update_schema` | Update a saved schema without an LLM call: rename, replace the schema_content, change tags, pin/unpin, or toggle non-determinism analysis. |
| Schemas | `delete_schema` | Soft-delete a saved schema by ID (restorable server-side shortly after; permanent deletion stays in the web UI). |
| Schemas | `analyze_sample_determinism` | Flag properties in a sample entity whose enriched value would DIFFER across models or reruns (non-deterministic names: temporal / ambiguous / subjective / multi-valued). |
| Schemas | `analyze_schema_determinism` | Analyze a saved schema and write a `non_determinism` flag onto each property whose enriched value is likely to vary across models/runs (badge in the editor). |
| Enrichment & fusion | `start_batch_enrichment` | Start an asynchronous batch enrichment against a JSON schema and return {job_id, total} immediately. |
| Enrichment & fusion | `fetch_entities` | Fetch a JSON array of entities from an external REST API (GET), server-side — the input step before start_batch_enrichment. |
| Enrichment & fusion | `enrich_entity` | Run a multi-model enrichment of a single entity against a JSON schema, returning the fused/best structured result. |
| Enrichment & fusion | `retry_expertises` | Re-run only the FAILED expertise domains of an existing multi-expertise enrichment record, merging the recovered values back into the record — no re-payment for the domains that… |
| Enrichment & fusion | `merge_records` | Merge 2+ enrichment records of the same entity into one fused result — the manual / re-run counterpart of the automatic fusion that follows a 2+ model enrich_entity or batch run. |
| Job control | `get_job_status` | Poll the status of an asynchronous LLM job — the middle step of every start → poll → fetch flow (start_batch_enrichment, generate_sample, run_benchmark, retry_expertises). |
| Job control | `cancel_job` | Cancel a pending, running, or paused LLM job started by start_batch_enrichment, generate_sample, run_benchmark, or retry_expertises. |
| Job control | `answer_job_question` | Answer the clarification questions of a paused job and resume it — the reply half of the interactive loop used by generate_sample's document-grounded planner (get_job_status… |
| Records & stats | `list_records` | List past enrichment records in your organization, most recent first. |
| Records & stats | `get_record` | Fetch a single enrichment record by ID, including the full structured output, validation errors, prompts/responses, and metrics. |
| Records & stats | `get_stats` | Aggregated statistics over your organization's enrichment records: totals, success rate, token usage, and cost summary. |
| Benchmarks | `list_benchmark_scenarios` | List the organization's benchmark scenarios (saved, reusable enrichment tests: schema + entity + strategy + scoring config). |
| Benchmarks | `get_benchmark_scenario` | Fetch one benchmark scenario with its per-model results (quality / cost / speed scores; results whose config_hash differs from the scenario's are stale — re-run those models). |
| Benchmarks | `create_benchmark_scenario` | Create a benchmark scenario — a reusable model test. |
| Benchmarks | `update_benchmark_scenario` | Update a benchmark scenario. |
| Benchmarks | `set_benchmark_reference` | Save a scenario's gold reference — the expected output each model result is scored against, and the gate between create_benchmark_scenario and run_benchmark. |
| Benchmarks | `delete_benchmark_scenario` | Delete a benchmark scenario and its results. |
| Benchmarks | `run_benchmark` | Launch a benchmark run — the final step of the benchmark lifecycle: execute the scenario's task (enrichment / sample generation / schema generation) with each selected model… |
| Attachments | `upload_attachment` | Upload a file (base64-encoded) so it can be used as source material