MCP Server for Codex and Other AI Clients

Codex, Cursor, VS Code with GitHub Copilot, Claude Code, and Claude connect to the same Entity Enricher MCP server. Their agents can design schemas, enrich entities in multiple languages, fuse models, curate semantic identities, benchmark quality, synchronize relational tables to a database — on the platform's models, or on the client's own model when the job delegates its LLM calls — and ask the product's support assistant when a question is about Entity Enricher itself.

Schema validation and agreement between models do not guarantee factual accuracy or freshness. Inspect sources, failures and partial database outcomes. The MCP provides conversational access; n8n and Make provide workflow automation over the same service.

Run jobs on your client's model

By default every start tool runs its job on your own model (use_platform_models=true, or naming a platform model, runs it on the platform's billed models instead). The job makes no platform model call and spends no credits: the model behind your MCP client — the one already holding your conversation, your documents and your connected tools — answers every model call of the job, and the platform keeps what it is good at: building the prompts, enforcing the output schema, validating and normalizing each answer, saving the records and syncing the databases.

  1. Start the job with no explicit model (omitted or auto), decidingenable_web_search where the tool takes it: omitted, it returns web_search_undecided so you ask the user first, since the search would be your own. The job pauses as soon as its first model call is ready.
  2. Read llm_requests on the job status: each entry is one model call in MCP sampling/createMessage shape — system prompt, messages, tools and toolChoice — with a purpose naming the step and a deadline. Binary attachments are referenced asenricher://attachments/{id} resources, never inlined; extracted text is already in the messages. A client that uploaded the file reads its own copy, so an attachment never requires a platform model.
  3. Run the request on your own model and hand the result back withanswer_llm_request. The platform validates it against the schema exactly as it validates a provider's answer; a rejected answer comes back as the same conversation with the error in a failed tool result, to fix and answer again.
  4. Repeat until the job completes. The records are stamped with the model key mcp::client at zero cost; an unanswered request fails the job after fifteen minutes.

Protocol details and edge cases — the opt-out, the web-search decision, concurrent requests, repair requests on enrichment, attachments, timeouts — are in the Delegated LLM calls guide listed below.

Quickstart

OAuth sign-in

OAuth lets a client connect without an API key. Entity Enricher's consent screen identifies the client, the organization, and the role granted to the connection. Access can be managed or revoked under API Keys → Connected Apps.

These examples use browser sign-in (OAuth) and the same Streamable HTTP endpoint: https://entityenricher.ai/api/mcp/, including the trailing slash. Each client has its own configuration format.

Codex

Codex shares MCP settings between its app, CLI, and IDE extension through ~/.codex/config.toml. The first command registers Entity Enricher; the login command opens browser sign-in when authentication is needed.

Codex CLI
codex mcp add entity-enricher --url https://entityenricher.ai/api/mcp/
codex mcp login entity-enricher
Codex documentation

Cursor

Cursor reads project servers from .cursor/mcp.json, or personal servers from ~/.cursor/mcp.json. The remote server entry uses mcpServers; Cursor handles the OAuth sign-in flow.

.cursor/mcp.json
{
  "mcpServers": {
    "entity-enricher": {
      "url": "https://entityenricher.ai/api/mcp/"
    }
  }
}
Cursor documentation

VS Code / GitHub Copilot

VS Code uses .vscode/mcp.json with a servers object and an explicit http transport. Starting the server makes its tools available to GitHub Copilot's agent after authorization.

.vscode/mcp.json
{
  "servers": {
    "entity-enricher": {
      "type": "http",
      "url": "https://entityenricher.ai/api/mcp/"
    }
  }
}
VS Code / GitHub Copilot documentation

Claude Code

This command registers a remote HTTP server in Claude Code. The /mcp command inside Claude Code opens its connection and authentication controls.

Claude Code CLI
claude mcp add --transport http entity-enricher https://entityenricher.ai/api/mcp/
Claude Code documentation

Claude / Claude Desktop

On claude.ai and Claude Desktop, the Connectors settings offer an "Add custom connector" action. The connector takes the server URL above and opens Entity Enricher's authorization screen. This hosted connection is configured through Connectors; claude_desktop_config.json is for local servers.

Claude connector documentation
  1. 1The organization the grant is scoped to
  2. 2The connection acts with your own role, never a wider one
  3. 3Revocable at any time from Connected Apps
The consent screen identifies the requesting client, the organization, and the role granted to the connection.

API-key authentication

Organization access keys are created under Settings → API Keys with a chosen role. Clients can send the key in an X-API-Key header instead of signing in with OAuth. For example, this Codex configuration reads the key from an environment variable:

~/.codex/config.toml
[mcp_servers.entity-enricher]
url = "https://entityenricher.ai/api/mcp/"
env_http_headers = { "X-API-Key" = "ENTITY_ENRICHER_API_KEY" }

ENTITY_ENRICHER_API_KEY must contain the key in the environment of the process running Codex. Cursor and VS Code accept this HTTP header in their own headers configuration object. The client references above describe their supported settings.

Example conversation

The same request works across clients: "List my Entity Enricher schemas, then enrich Sanofi using my pharmaceutical company schema and show the saved result."The client discovers the tools and uses them to select a schema and run enrichment. Confirmation prompts, progress display, and resource access depend on the client.

Tools

62 tools cover schema authoring, enrichment, benchmarks, database sync, semantic identities and product support. They reuse backend services for validation, billing and processing. Each tool exposes its own supported parameters. Long-running work (batch enrichment, sample generation, benchmark runs) is asynchronous: the start tool returns a job_id, the client polls get_job_statusand reads the resulting records or benchmark results. Inspect failures and partial outcomes before reporting success.

CategoryToolDescription
Discoverylist_modelsList available model keys, nominal capabilities, languages, strategies, auto-selected defaults and organization profile_limits.
Schemasgenerate_sampleGenerate editable sample JSON from a free-text request for schema authoring.
Schemaslist_schemasList saved schemas in your organization, pinned first.
Schemasget_schemaRead a saved schema with its properties, annotations and input_contract.
Schemascreate_schema_from_sampleGenerate and auto-save a schema from reviewed samples, returning schema_id, schema content and record links.
Schemassave_schemaSave a directly authored schema and return its ID and link.
Schemasupdate_schemaEdit a saved schema's metadata or replace its full schema_content without an LLM call.
Schemasget_schema_partRead only the schema fragment needed for an edit.
Schemasget_enum_candidatesList observed values outside each open enum's current vocabulary, with counts from recent enrichment records.
Schemasupdate_schema_propertyEdit or remove one property by path without replacing the full schema.
Schemasadd_schema_propertyAdd a property under the root (parent_path='), an object path or '$defs.X'.
Schemasmove_schema_propertyMove one property into the root, an object path or '$defs.X', preserving its flags and expertise.
Schemasresolve_unify_proposalResolve one pending entity-type unification proposal from get_schema.
Schemasnest_schema_regionMaterialize an entity region from get_schema's x-entityMap.
Schemaspublish_schemaPublish a database-linked schema's working copy as the contract used by enrichment and replicas.
Schemasdelete_schemaSoft-delete a saved schema by UUID.
Schemasanalyze_sampleAnalyze sample property ambiguity and relationship identity scoping before schema generation.
Schemasanalyze_schemaAnalyze a saved schema's property ambiguity and relationship identity scoping, writing annotations to the schema.
Enrichment & fusionstart_batch_enrichmentStart billed asynchronous enrichment of an entity list against exactly one of schema_id or target_schema.
Enrichment & fusionenrich_entityEnrich one entity against exactly one of schema_id or target_schema, returning structured output, record_id, costs and any database outcome.
Enrichment & fusionretry_expertisesRetry only an existing record's failed expertise domains, then update its output and attempt the run's fusion/synchronization.
Enrichment & fusionmerge_recordsFuse two or more records of the same entity into a new arbitration record.
Job controlget_job_statusRead a job's status, progress and compact terminal summary with persisted record IDs.
Job controlcancel_jobRequest cancellation of a pending, running or paused LLM job.
Job controlanswer_job_questionResume a paused job with answers to the questions returned under pause.
Job controlanswer_llm_requestSubmit the result of one pending model call of a delegated job: a job the user started on the client's own model (every start tool's default unless use_platform_models=true or an…
Records & statslist_recordsList compact, paginated records in your organization, most recent first.
Records & statsget_recordRead one persisted record's structured_output, entity_input_data, validation errors, expertise verdicts and metrics.
Records & statsget_statsRead organization-wide record totals, success rate, tokens and cost summary.
Benchmarkslist_benchmark_scenariosList compact benchmark scenario summaries and total.
Benchmarksget_benchmark_scenarioRead one benchmark scenario with per-model quality, cost and speed results.
Benchmarksget_benchmark_scenario_resultsFilter, rank and limit a scenario's per-model benchmark results.
Benchmarkscreate_benchmark_scenarioCreate a reusable benchmark with a mandatory scoring judge.
Benchmarksupdate_benchmark_scenarioEdit a benchmark's test definition or scoring configuration.
Benchmarksset_benchmark_referenceSave the gold reference for an enrichment or schema-generation benchmark.
Benchmarksrevert_benchmark_reference_updatesUndo automatic edits a scoring pass made to a scenario's reference.
Benchmarksdelete_benchmark_scenarioDelete a benchmark scenario and its stored results.
Benchmarksrun_benchmarkStart billed asynchronous execution and scoring of a benchmark.
Attachmentsupload_attachmentUpload base64 file bytes as reusable source material; returns id and requires_capability.
Attachmentsdelete_attachmentPermanently delete an attachment in your organization, including its stored file.
Database Synclist_database_syncsList a saved schema's database registrations, linked schemas, options and sync hosts.
Database Synclist_entity_statesBrowse a schema's current merged entity rows, not per-run records.
Database Synccreate_database_syncRegister a saved schema for relational synchronization to PostgreSQL, MySQL or SQLite.
Database Syncassign_sync_hostAssign or clear the host provisioning a database sync.
Database Syncclassify_database_modelStart a billed analysis proposing database keys, SQL types, indexes and relationship ownership on a linked schema.
Database Syncdelete_database_syncDelete a database registration and its queued deltas, stopping its feed.
Database Syncget_database_setup_instructionsReturn non-secret install, browser-confirmed pairing and run instructions for an ee-database sync client.
Database Syncfetch_database_deltasRead the next ordered window of SQL deltas and canonical payloads for a database sync.
Database Syncack_database_deltasAcknowledge every delta through up_to_id after successful application, releasing its lease.
Database Syncsync_records_to_databaseValidate and inject stored or supplied enrichment output into the entity layer and linked syncs.
Semantic IDslist_semantic_conceptsBrowse organization concepts with aliases, usage counts and type/model facets.
Semantic IDsget_semantic_conceptRead one concept's aliases, identity source keys, linked records and nearest neighbors within its own type/model slice.
Semantic IDsprobe_semantic_conceptPreview identity resolution without adding a concept or increasing its usage.
Semantic IDsadd_semantic_conceptAdd an identity concept at zero usage, or add text as an alias using alias_of.
Semantic IDsupdate_concept_aliasRemove or promote a concept alias using alias IDs from get_semantic_concept.
Semantic IDsimport_semantic_conceptsResolve 1..1000 texts against one concept type.
Semantic IDsmerge_semantic_conceptsMerge a loser concept into a winner.
Semantic IDsdelete_semantic_conceptsDelete concepts selected by ids, concept_types or unused_only.
Semantic IDsmigrate_semantic_embeddingsInspect or migrate the organization's concept embedding space.
Product supportask_supportAsk Rupert, Entity Enricher's product-support assistant, a question about the application itself: how a feature, a tool or a setting works, what an error_code, a limit, a status…
Product supportget_support_conversationRead one of your support threads with every turn: your questions (role user), Rupert's answers (assistant) and the support team's follow-ups (admin, with author_name).
Product supportlist_support_conversationsYour support threads, newest activity first, with message_count and unread_for_user (a support team follow-up you have not read).

Workflow guides, loaded when needed

Server instructions explain the available workflows; tool descriptions explain individual calls. For modeling decisions or recovery, your client can read the guide index at enricher://docs and select a guide through MCP resources. Reading a guide does not run a model. The links below open the same English guides in the public repository.

Resources

Resources expose schema and record data, plus workflow guides, as Markdown. Clients choose how to discover and load them; resource content can still consume model context.

URI templateDescription
enricher://docsIndex of the workflow guides, each available at its listed resource URI.
enricher://schemas/{schema_id}A saved schema working copy as Markdown; use get_schema with version="published" for the active linked contract.
enricher://records/{record_id}A past enrichment record rendered as Markdown — metadata + structured output + validation errors.
enricher://attachments/{attachment_id}The bytes of an uploaded attachment, served with their real media type — how a job that delegates its LLM calls hands your client a PDF, image or audio file it did not upload itself.

Product support from your client

When a question is about Entity Enricher itself — how a feature or a tool works, what an error code, a limit or a warning means, why a result looks the way it does — and the guides do not answer it, the server instructions tell the agent to ask Rupert, the product-support assistant, with ask_support rather than guess. The call returns the complete answer and the id of the thread it opened; passing thatconversation_id to the next question keeps the context of the exchange.

Each question counts against the organization's daily support quota, reported asquestions_remaining. The support team may answer in the thread: the next ask_support on it returns those follow-ups asnew_admin_messages, andget_support_conversation reads a whole thread. The same threads appear in the web app's support chat and, for owners, in the Users page's Discussions tab, badged as opened by an AI agent.

Interactive classification handling

When you ask enrich_entity to use a classification model and the entity doesn't match the schema type, the tool returns anon-error response with structured details. The client reads it, surfaces the reasoning to you, and (on your confirmation) retries with force_after_classification_warning=true — which drops the classifier on the retry.

{
  "success": false,
  "error_code": "classification_warning",
  "message": "Pre-flight classification rejected the entity. ...",
  "classification": {
    "status": "mismatch",
    "reasoning": "Titan is a moon of Saturn, not a planet.",
    "confidence": 0.97
  },
  "job_id": "..."
}

The MCP response preserves the classification details so your client can explain the decision before starting a new call.

The same interactivity powers a second flow: when generate_sample runs with source documents, its planner may pause with structural clarification questions. The client relays them to you and resumes the job with answer_job_question — round after round, until the sample is generated.

Error codes

Most tool errors return a structured object with an error_code field so the client can distinguish quota, classification, timeout and provider failures. Some older responses carry only an error or message field; inspect the actual result as well as the transport status.

error_codeWhen
invalid_requestMalformed UUID, mutually exclusive args (schema_id + target_schema), or request body validation failed.
prompt_limit_reachedDaily / weekly / monthly prompt quota exhausted (HTTP 402). Body includes period, limit, used, needed.
insufficient_creditsOrg has billing enabled but credit balance is too low to start the job (HTTP 402). Body includes balance and a purchase URL.
model_limit_exceededAsked for more models than the plan allows (HTTP 402). Echoes limit + requested.
language_limit_exceededAsked for more languages than the plan allows (HTTP 402).
concurrent_job_limit_reachedToo many active enrichment jobs for this org. Wait or upgrade plan.
classification_warning⚡ Non-error: pre-flight classifier rejected the entity. Response carries the classification context so the client can ask the user to confirm and retry with force_after_classification_warning=true.
benchmarks_not_in_planThe organization plan does not include Model Benchmarks (HTTP 403). Mutating benchmark tools also check the owner role.
support_question_limit_reachedThe organization's daily support-question quota is spent (HTTP 402). Body includes limit and used; every ask_support result reports questions_remaining.
support_requires_userask_support was called with an organization access key (HTTP 403). A support thread belongs to a person: sign in with OAuth or a personal API key.
support_unavailableThe support assistant could not answer (relay failure). The question still counts and the thread exists: read it later with get_support_conversation rather than asking again at once.
web_search_undecidedA start tool was called without enable_web_search for a job running on your model. Ask the user whether your model may use web search, then call again with enable_web_search=true or false.
delegation_requires_autoA job running on your model met an explicit platform model injected after launch, such as an organization default (HTTP 400). Start the job with use_platform_models=true, or drop that default.
request_not_pendinganswer_llm_request named a request that was already answered, expired, or belongs to a job that moved on. Read get_job_status(job_id).llm_requests for what is pending now.
llm_request_pendinganswer_job_question was called on a job paused on delegated LLM requests, not on a question. Answer them with answer_llm_request.
llm_request_timeoutA job delegating its LLM calls got no answer to a pending request within 15 minutes; the job failed. Delegated jobs have no default answer.
ambiguity_check_disabledanalyze_schema was called on a schema whose ambiguity check is toggled off (HTTP 400). Re-enable it via update_schema with ambiguity_check_enabled=true first.
enrichment_timeoutJob exceeded timeout_seconds. Suggest fewer models or splitting the entity.
schema_generation_timeoutSchema generation exceeded timeout_seconds.
schema_generation_failedUpstream LLM error during schema generation (HTTP 502).
model_output_invalidThe model returned output that does not match the schema (HTTP 502). Body names the model, the offending property path, and retryable: true — call the tool again, or pick a stronger model.
cancelledJob was cancelled mid-run (HTTP 499).
not_foundSchema or record ID does not exist in your org.
http_errorCatch-all for HTTP errors without a structured detail body.

Deliberate omissions

See also