面向 Codex 和其他 AI 客户端的 MCP 服务器

Codex、Cursor、搭载 GitHub Copilot 的 VS Code、Claude Code 和 Claude 均连接到同一个 Entity Enricher MCP 服务器。它们的智能体可以设计模式、以多种语言增强实体、融合模型、整理语义标识、对质量进行基准测试、将关系表同步到数据库——既可使用平台的模型,也可在任务委派其 LLM 调用时使用客户自有的模型——并在问题涉及 Entity Enricher 本身时向产品的支持助手提问。

模式校验以及模型之间的一致性并不能保证内容的事实准确性或时效性。请检查来源、失败项以及部分写入数据库的结果。MCP 提供对话式访问;n8n 和 Make 基于同一服务提供工作流自动化。

在您客户端的模型上运行任务

默认情况下,每个启动工具都在你自己的模型上运行其任务(设置 use_platform_models=true 或指定平台模型,则改为使用平台的计费模型运行)。该任务不会发起任何平台模型调用,也不消耗积分:由你的 MCP 客户端背后的模型——即已经掌握你的对话、文档和已连接工具的那个模型——回答任务的每一次模型调用,而平台继续做它擅长的事:构建提示词、强制执行输出架构、校验并规范化每个回答、保存记录并同步数据库。

  1. 启动任务时不指定显式模型(省略或 auto),并在工具接受该参数时决定enable_web_search:若省略,它会返回 web_search_undecided,因此请先询问用户,因为搜索将由你自己执行。任务会在第一次模型调用准备好时立即暂停。
  2. 读取作业状态中的 llm_requests:每个条目对应一次模型调用,采用 MCP sampling/createMessage 格式——系统提示词、消息、工具和 toolChoice——并带有标明步骤的 purpose 以及截止时间。二进制附件以enricher://attachments/{id} 资源形式引用,绝不内联;提取出的文本已包含在消息中。上传了该文件的客户端会读取自己的副本,因此附件绝不需要平台模型。
  3. 在你自己的模型上执行该请求,并通过answer_llm_request 将结果回传。平台会像校验提供商的回答一样,严格依照模式对其进行校验;被拒绝的回答会以同一会话返回,错误包含在失败的工具结果中,便于修正后重新回答。
  4. 重复该过程直到任务完成。记录会以模型键 mcp::client 标记,成本为零;请求若十五分钟内未得到回答,任务即失败。

协议细节与边界情况——退出机制、网络搜索决策、并发请求、丰富化过程中的修复请求、附件、超时——详见下方列出的 委托 LLM 调用 指南。

快速开始

OAuth 登录

OAuth 让客户端无需 API 密钥即可连接。Entity Enricher 的授权确认页面会标明客户端、组织以及授予该连接的角色。可在 API 密钥 → 已连接应用 下管理或撤销访问权限。

这些示例使用浏览器登录 (OAuth) 和同一个 Streamable HTTP 端点:https://entityenricher.ai/api/mcp/,包括末尾的斜杠。每个客户端都有自己的配置格式。

Codex

Codex 通过 ~/.codex/config.toml 在其应用、CLI 和 IDE 扩展之间共享 MCP 设置。第一条命令用于注册 Entity Enricher;需要身份验证时,login 命令会打开浏览器登录。

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

Cursor

Cursor 从 .cursor/mcp.json 读取项目服务器,或从 ~/.cursor/mcp.json 读取个人服务器。远程服务器条目使用 mcpServers;OAuth 登录流程由 Cursor 处理。

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

VS Code / GitHub Copilot

VS Code 使用 .vscode/mcp.json,其中包含 servers 对象和显式的 http 传输。启动服务器后,经过授权即可将其工具提供给 GitHub Copilot 的智能体使用。

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

Claude Code

此命令会在 Claude Code 中注册远程 HTTP 服务器。在 Claude Code 内使用 /mcp 命令可打开其连接和身份验证控制项。

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

Claude / Claude Desktop

在 claude.ai 和 Claude Desktop 中,连接器设置提供“添加自定义连接器”操作。该连接器使用上述服务器 URL,并会打开 Entity Enricher 的授权页面。此托管连接通过连接器设置进行配置;claude_desktop_config.json 仅用于本地服务器。

Claude 连接器文档
  1. 1本次授权所限定的组织
  2. 2该连接以你本人的角色执行操作,绝不会获得更大的权限
  3. 3可随时在“已连接应用”中撤销
授权确认页面会标明发起请求的客户端、组织以及授予该连接的角色。

API 密钥身份验证

组织访问密钥在 设置 → API 密钥 下创建,并可选择角色。客户端可以在 X-API-Key 标头中发送该密钥,而无需使用 OAuth 登录。例如,以下 Codex 配置从环境变量读取密钥:

~/.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 必须在运行 Codex 的进程环境中包含该密钥。Cursor 和 VS Code 可在各自的 headers 配置对象中接受此 HTTP 标头。上述客户端参考文档说明了它们支持的设置。

对话示例

同一个请求在各客户端中均可使用:“列出我的 Entity Enricher 模式,然后使用我的制药公司模式丰富化 Sanofi 并显示已保存的结果。”客户端会发现这些工具,并用它们选择模式并运行丰富化。确认提示、进度显示和资源访问方式取决于具体客户端。

工具

62 个工具涵盖模式编写、增强、基准测试、数据库同步、语义标识和产品支持。它们复用后端服务完成校验、计费和处理。每个工具都公开各自支持的参数。长时间运行的任务(批量增强、样本生成、基准测试运行)是异步的:启动工具返回 job_id,客户端轮询 get_job_status并读取生成的记录或基准测试结果。在报告成功之前,请先检查失败情况和部分结果。

类别工具描述
发现list_models列出可用的模型键、标称能力、语言、策略、自动选择的默认值以及组织的 profile_limits。
Schemagenerate_sample根据自由文本请求生成可编辑的样本 JSON,用于模式编写。
Schemalist_schemas列出组织中已保存的模式,置顶的排在前面。
Schemaget_schema查看已保存的模式及其属性、注解和 input_contract。
Schemacreate_schema_from_sample根据已审核的样本生成并自动保存模式,返回 schema_id、模式内容和记录链接。
Schemasave_schema保存直接编写的模式,并返回其 ID 和链接。
Schemaupdate_schema编辑已保存模式的元数据,或无需调用 LLM 即可替换其完整的 schema_content。
Schemaget_schema_part仅读取编辑所需的模式片段。
Schemaget_enum_candidates列出各开放枚举当前词汇表之外的已观测值,并附上近期富集记录中的出现次数。
Schemaupdate_schema_property按路径编辑或删除单个属性,无需替换整个模式。
Schemaadd_schema_property在根节点 (parent_path=')、某个对象路径或 '$defs.X' 下添加属性。
Schemamove_schema_property将某个属性移动到根、对象路径或 '$defs.X' 下,同时保留其标记和专业领域。
Schemaresolve_unify_proposal处理 get_schema 中一条待定的实体类型统一提议。
Schemanest_schema_region根据 get_schema 的 x-entityMap 具体化一个实体区域。
Schemapublish_schema将数据库关联模式的工作副本发布为富集和副本所使用的契约。
Schemadelete_schema按 UUID 软删除已保存的模式。
Schemaanalyze_sample在生成模式之前,先分析样本的属性歧义与关系身份作用域。
Schemaanalyze_schema分析已保存模式的属性歧义与关系身份作用域,并将注释写入该模式。
增强与融合start_batch_enrichment对实体列表启动计费的异步富化,schema_id 与 target_schema 必须且只能提供其一。
增强与融合enrich_entity针对 schema_id 或 target_schema 二者之一(且仅一个)增强单个实体,返回结构化输出、record_id、成本以及任何数据库处理结果。
增强与融合retry_expertises仅重试现有记录中失败的专业领域,然后更新其输出并尝试本次运行的融合/同步。
增强与融合merge_records将同一实体的两条或多条记录融合为一条新的仲裁记录。
作业控制get_job_status查看作业的状态、进度,以及包含已持久化记录 ID 的精简终态摘要。
作业控制cancel_job请求取消处于待处理、运行中或已暂停状态的 LLM 作业。
作业控制answer_job_question提供暂停时返回问题的答案,以恢复已暂停的作业。
作业控制answer_llm_request提交委托作业中一个待处理模型调用的结果:委托作业是指用户在客户端自有模型上启动的作业(这是所有启动类工具的默认方式,除非设置了 use_platform_models=true 或…
记录与统计list_records分页列出组织中的精简记录,最新的排在前面。
记录与统计get_record查看单条已持久化记录的 structured_output、entity_input_data、校验错误、专业领域判定和指标。
记录与统计get_stats查看组织范围内的记录总数、成功率、令牌数和成本汇总。
基准测试list_benchmark_scenarios列出精简的基准测试场景摘要及总数。
基准测试get_benchmark_scenario查看单个基准测试场景,包含各模型的质量、成本和速度结果。
基准测试get_benchmark_scenario_results筛选、排序并限制某个场景各模型的基准测试结果。
基准测试create_benchmark_scenario创建可复用的基准测试,必须配置评分判定器。
基准测试update_benchmark_scenario编辑基准测试的测试定义或评分配置。
基准测试set_benchmark_reference保存富化或模式生成基准测试的黄金参考答案。
基准测试revert_benchmark_reference_updates撤销某轮评分对场景参考答案所做的自动修改。
基准测试delete_benchmark_scenario删除基准测试场景及其已存储的结果。
基准测试run_benchmark启动计费的异步基准测试执行与评分。
附件upload_attachment以 base64 上传文件字节作为可复用的源材料;返回 id 和 requires_capability。
附件delete_attachment永久删除组织中的某个附件,包括其存储的文件。
Database Synclist_database_syncs列出已保存模式的数据库注册、关联模式、选项和同步主机。
Database Synclist_entity_states浏览某个模式当前已合并的实体行,而非单次运行的记录。
Database Synccreate_database_sync注册已保存的模式,以便关系型同步到 PostgreSQL、MySQL 或 SQLite。
Database Syncassign_sync_host指定或清除负责配置数据库同步的主机。
Database Syncclassify_database_model针对已关联的模式启动计费分析,提出数据库键、SQL 类型、索引和关系归属建议。
Database Syncdelete_database_sync删除数据库注册及其排队中的增量,停止其数据推送。
Database Syncget_database_setup_instructions返回 ee-database sync 客户端的非机密安装说明、浏览器确认的配对说明和运行说明。
Database Syncfetch_database_deltas读取数据库同步的下一个有序 SQL 增量与规范化载荷窗口。
Database Syncack_database_deltas成功应用后,通过 up_to_id 确认每个增量,并释放其租约。
Database Syncsync_records_to_database校验已存储或所提供的富化输出,并将其注入实体层和已关联的同步。
语义 IDlist_semantic_concepts浏览组织概念,包含别名、使用次数以及类型/模型分面。
语义 IDget_semantic_concept查看单个概念的别名、身份来源键、关联记录,以及其所属类型/模型切片内的最近邻。
语义 IDprobe_semantic_concept预览身份解析,不会新增概念或增加其使用次数。
语义 IDadd_semantic_concept以零使用量添加身份概念,或使用 alias_of 将文本添加为别名。
语义 IDupdate_concept_alias使用 get_semantic_concept 返回的别名 ID 删除或提升概念别名。
语义 IDimport_semantic_concepts针对单个概念类型解析 1..1000 条文本。
语义 IDmerge_semantic_concepts将落选概念合并到胜出概念中。
语义 IDdelete_semantic_concepts按 ids、concept_types 或 unused_only 选择并删除概念。
语义 IDmigrate_semantic_embeddings查看或迁移组织的概念嵌入空间。
产品支持ask_support向 Entity Enricher 的产品支持助手 Rupert 提问,咨询应用本身的问题:某项功能、工具或设置如何使用,某个 error_code、限额或状态代表什么……
产品支持get_support_conversation读取您的某个支持会话及其每一轮消息:您的提问(role 为 user)、Rupert 的回答(assistant)以及支持团队的后续回复(admin,含 author_name)。
产品支持list_support_conversations您的支持会话,按最新动态排序,包含 message_count 和 unread_for_user(您尚未阅读的支持团队后续回复)。

按需加载的工作流指南

服务器说明介绍可用的工作流;工具说明解释单个调用。如需进行建模决策或故障恢复,你的客户端可在 enricher://docs 读取指南索引,并通过 MCP 资源选择指南。阅读指南不会运行模型。下方链接会打开公共仓库中相同的英文指南。

资源

资源以 Markdown 形式提供模式和记录数据以及工作流指南。客户端自行决定如何发现和加载它们;资源内容仍会占用模型上下文。

URI 模板描述
enricher://docs工作流指南索引,每个指南均可通过其列出的资源 URI 访问。
enricher://schemas/{schema_id}已保存模式工作副本的 Markdown 形式;如需当前关联生效的契约,请使用 get_schema 并设置 version="published"。
enricher://records/{record_id}以 Markdown 呈现的过往扩充记录——元数据 + 结构化输出 + 校验错误。
enricher://attachments/{attachment_id}已上传附件的字节内容,以其真实媒体类型提供——委托 LLM 调用的作业正是借此将并非由您的客户端上传的 PDF、图像或音频文件交给客户端。

在你的客户端中获取产品支持

当问题涉及 Entity Enricher 本身——某项功能或工具如何运作,某个错误码、限制或警告意味着什么,结果为何呈现这样——而指南无法解答时,服务器指令会要求智能体使用 ask_support 向产品支持助手 Rupert 提问,而不是凭猜测作答。该调用会返回完整答案以及其所创建会话的 id;将该conversation_id 传给下一个问题即可保留本次交流的上下文。

每个问题都会计入组织的每日支持配额,并在questions_remaining中报告。支持团队可能会在会话中回复:下一次针对该会话的 ask_support 会将这些后续回复作为new_admin_messages返回,而get_support_conversation 可读取整个会话。相同的会话也会显示在网页应用的支持聊天中;对所有者而言,还会显示在“用户”页面的“讨论”标签页中,并标记为由 AI 智能体发起。

交互式分类处理

当你要求 enrich_entity 使用分类模型,而实体与架构类型不匹配时,该工具会返回一个非错误响应,其中包含结构化详情。客户端读取该响应后会向你说明判断依据,并在你确认后使用 force_after_classification_warning=true 重试 —— 该参数会在重试时跳过分类器。

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

MCP 响应会保留分类详情,以便你的客户端在发起新调用前解释该决策。

同样的交互机制还支撑着第二种流程:当 generate_sample 在有源文档的情况下运行时,其规划器可能会暂停并提出结构性澄清问题。客户端会将这些问题转达给你,并通过 answer_job_question 继续该任务 —— 一轮接一轮,直到生成样本。

错误代码

大多数工具错误会返回带有 error_code 字段的结构化对象,便于客户端区分配额、分类、超时和提供商故障。部分较早的响应仅包含 error 或 message 字段;请同时检查实际结果和传输状态。

error_code时间
invalid_requestUUID 格式错误、参数互斥(schema_id + target_schema),或请求体验证失败。
prompt_limit_reached每日/每周/每月 prompt 配额已用尽(HTTP 402)。响应体包含 period、limit、used、needed。
insufficient_credits组织已启用计费,但信用额余额过低,无法启动任务(HTTP 402)。响应正文包含余额和购买链接。
model_limit_exceeded请求的模型数量超出套餐允许范围(HTTP 402)。会回显限制值与请求值。
language_limit_exceeded请求的语言数量超出套餐允许范围(HTTP 402)。
concurrent_job_limit_reached该组织正在运行的富集任务过多。请等待或升级套餐。
classification_warning⚡ 非错误:预检分类器拒绝了该实体。响应中附带分类上下文,客户端可据此请求用户确认,并使用 force_after_classification_warning=true 重试。
benchmarks_not_in_plan该组织套餐不包含模型基准测试(HTTP 403)。变更类基准测试工具还会校验所有者角色。
support_question_limit_reached组织的每日支持提问配额已用尽(HTTP 402)。响应正文包含 limit 和 used;每个 ask_support 结果都会报告 questions_remaining。
support_requires_user调用 ask_support 时使用了组织访问密钥(HTTP 403)。支持会话归属于个人:请使用 OAuth 或个人 API 密钥登录。
support_unavailable支持助手无法作答(转发失败)。该问题仍会计入配额,且会话已创建:请稍后使用 get_support_conversation 读取,而不要立即重复提问。
web_search_undecided为在你的模型上运行的任务调用启动工具时未提供 enable_web_search。请先询问用户是否允许你的模型使用网络搜索,然后以 enable_web_search=true 或 false 重新调用。
delegation_requires_auto在你的模型上运行的任务遇到了启动后注入的显式平台模型,例如组织默认模型(HTTP 400)。请以 use_platform_models=true 启动该任务,或移除该默认设置。
request_not_pendinganswer_llm_request 指定的请求已被回答、已过期,或其所属任务已继续执行。请查看 get_job_status(job_id).llm_requests 了解当前待处理的请求。
llm_request_pendinganswer_job_question 被用于一个因委托 LLM 请求而暂停的任务,而非因问题而暂停。请使用 answer_llm_request 回答这些请求。
llm_request_timeout某个委托 LLM 调用的任务在 15 分钟内未收到待处理请求的回答,该任务已失败。委托任务没有默认回答。
ambiguity_check_disabled对一个已关闭歧义检查的架构调用了 analyze_schema(HTTP 400)。请先通过 update_schema 设置 ambiguity_check_enabled=true 重新启用。
enrichment_timeout作业超过 timeout_seconds。建议减少模型数量或拆分实体。
schema_generation_timeoutSchema 生成超过 timeout_seconds。
schema_generation_failed生成 schema 时上游 LLM 出错(HTTP 502)。
model_output_invalid模型返回的输出与 schema 不匹配(HTTP 502)。响应正文中会给出模型名称、出错的属性路径以及 retryable: true —— 请再次调用该工具,或选择更强的 model。
cancelled作业在运行中被取消(HTTP 499)。
not_foundSchema 或记录 ID 在您的组织中不存在。
http_error用于捕获没有结构化详情正文的 HTTP 错误。

有意省略的部分

另请参阅