Servidor MCP para Codex y otros clientes de IA

Codex, Cursor, VS Code con GitHub Copilot, Claude Code y Claude se conectan al mismo servidor MCP de Entity Enricher. Sus agentes pueden diseñar esquemas, enriquecer entidades en varios idiomas, fusionar modelos, curar identidades semánticas, evaluar la calidad con benchmarks, sincronizar tablas relacionales con una base de datos —con los modelos de la plataforma o con el modelo propio del cliente cuando el trabajo delega sus llamadas al LLM— y preguntar al asistente de soporte del producto cuando la duda es sobre Entity Enricher.

La validación de esquema y la coincidencia entre modelos no garantizan la exactitud ni la actualidad de los datos. Inspeccione las fuentes, los fallos y los resultados parciales en la base de datos. El MCP ofrece acceso conversacional; n8n y Make ofrecen automatización de flujos de trabajo sobre el mismo servicio.

Ejecute trabajos con el modelo de su cliente

De forma predeterminada, cada herramienta de inicio ejecuta su trabajo en su propio modelo (use_platform_models=true, o indicar un modelo de plataforma, lo ejecuta en los modelos facturados de la plataforma). El trabajo no realiza ninguna llamada a los modelos de la plataforma y no consume créditos: el modelo que hay detrás de su cliente MCP —el que ya contiene su conversación, sus documentos y sus herramientas conectadas— responde a todas las llamadas al modelo del trabajo, y la plataforma conserva aquello en lo que destaca: construir los prompts, aplicar el esquema de salida, validar y normalizar cada respuesta, guardar los registros y sincronizar las bases de datos.

  1. Inicie el trabajo sin un modelo explícito (omitido o auto), decidiendoenable_web_search cuando la herramienta lo acepte: si se omite, devuelve web_search_undecided para que pregunte antes al usuario, ya que la búsqueda sería suya. El trabajo se pausa en cuanto su primera llamada al modelo está lista.
  2. Lea llm_requests en el estado del trabajo: cada entrada es una llamada al modelo con la forma sampling/createMessage de MCP (prompt del sistema, mensajes, herramientas y toolChoice), con un purpose que nombra el paso y una fecha límite. Los adjuntos binarios se referencian como recursosenricher://attachments/{id}, nunca se incluyen en línea; el texto extraído ya está en los mensajes. Un cliente que subió el archivo lee su propia copia, por lo que un adjunto nunca requiere un modelo de la plataforma.
  3. Ejecute la solicitud en su propio modelo y devuelva el resultado conanswer_llm_request. La plataforma lo valida contra el esquema igual que valida la respuesta de un proveedor; una respuesta rechazada vuelve como la misma conversación con el error en un tool result fallido, para corregirla y responder de nuevo.
  4. Repita hasta que el trabajo finalice. Los registros se marcan con la clave de modelo mcp::client sin coste alguno; una solicitud sin responder hace fallar el trabajo al cabo de quince minutos.

Los detalles del protocolo y los casos límite —la exclusión, la decisión sobre la búsqueda web, las solicitudes concurrentes, las solicitudes de corrección en el enriquecimiento, los archivos adjuntos, los tiempos de espera— se encuentran en la guía Llamadas LLM delegadas que figura a continuación.

Inicio rápido

Inicio de sesión con OAuth

OAuth permite que un cliente se conecte sin clave de API. La pantalla de consentimiento de Entity Enricher identifica el cliente, la organización y el rol concedido a la conexión. El acceso se puede gestionar o revocar en Claves de API → Aplicaciones conectadas.

Estos ejemplos usan el inicio de sesión en el navegador (OAuth) y el mismo endpoint Streamable HTTP: https://entityenricher.ai/api/mcp/, incluida la barra final. Cada cliente tiene su propio formato de configuración.

Codex

Codex comparte la configuración MCP entre su aplicación, su CLI y su extensión para IDE a través de ~/.codex/config.toml. El primer comando registra Entity Enricher; el comando de inicio de sesión abre la autenticación en el navegador cuando es necesario.

Codex CLI
codex mcp add entity-enricher --url https://entityenricher.ai/api/mcp/
codex mcp login entity-enricher
Documentación de Codex

Cursor

Cursor lee los servidores del proyecto desde .cursor/mcp.json, o los servidores personales desde ~/.cursor/mcp.json. La entrada del servidor remoto usa mcpServers; Cursor gestiona el flujo de inicio de sesión con OAuth.

.cursor/mcp.json
{
  "mcpServers": {
    "entity-enricher": {
      "url": "https://entityenricher.ai/api/mcp/"
    }
  }
}
Documentación de Cursor

VS Code / GitHub Copilot

VS Code usa .vscode/mcp.json con un objeto servers y un transporte http explícito. Al iniciar el servidor, sus herramientas quedan disponibles para el agente de GitHub Copilot tras la autorización.

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

Claude Code

Este comando registra un servidor HTTP remoto en Claude Code. El comando /mcp dentro de Claude Code abre sus controles de conexión y autenticación.

Claude Code CLI
claude mcp add --transport http entity-enricher https://entityenricher.ai/api/mcp/
Documentación de Claude Code

Claude / Claude Desktop

En claude.ai y Claude Desktop, la configuración de Conectores ofrece la acción "Añadir conector personalizado". El conector toma la URL del servidor indicada arriba y abre la pantalla de autorización de Entity Enricher. Esta conexión alojada se configura desde Conectores; claude_desktop_config.json es para servidores locales.

Documentación del conector de Claude
  1. 1La organización a la que se limita la concesión
  2. 2La conexión actúa con su propio rol, nunca con uno más amplio
  3. 3Revocable en cualquier momento desde Aplicaciones conectadas
La pantalla de consentimiento identifica el cliente que realiza la solicitud, la organización y el rol concedido a la conexión.

Autenticación por clave de API

Las claves de acceso de la organización se crean en Configuración → Claves de API con el rol que elija. Los clientes pueden enviar la clave en una cabecera X-API-Key en lugar de iniciar sesión con OAuth. Por ejemplo, esta configuración de Codex lee la clave desde una variable de entorno:

~/.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 debe contener la clave en el entorno del proceso que ejecuta Codex. Cursor y VS Code admiten esta cabecera HTTP en su propio objeto de configuración headers. Las referencias de cliente anteriores describen los ajustes compatibles.

Ejemplo de conversación

La misma petición funciona en todos los clientes: "Enumera mis esquemas de Entity Enricher, luego enriquece Sanofi con mi esquema de empresa farmacéutica y muestra el resultado guardado."El cliente descubre las herramientas y las usa para seleccionar un esquema y ejecutar el enriquecimiento. Los mensajes de confirmación, la visualización del progreso y el acceso a los recursos dependen del cliente.

Herramientas

62 herramientas abarcan la creación de esquemas, el enriquecimiento, los benchmarks, Database Sync, las identidades semánticas y el soporte del producto. Reutilizan los servicios del backend para la validación, la facturación y el procesamiento. Cada herramienta expone sus propios parámetros admitidos. Las tareas de larga duración (enriquecimiento por lotes, generación de muestras, ejecuciones de benchmark) son asíncronas: la herramienta de inicio devuelve un job_id, el cliente consulta get_job_statusy lee los registros resultantes o los resultados del benchmark. Revise los errores y los resultados parciales antes de informar de que la operación fue correcta.

CategoríaHerramientaDescripción
Descubrimientolist_modelsEnumere las claves de modelo disponibles, las capacidades nominales, los idiomas, las estrategias, los valores predeterminados autoseleccionados y los profile_limits de la organización.
Esquemasgenerate_sampleGenere una muestra JSON editable a partir de una solicitud en texto libre para la creación de esquemas.
Esquemaslist_schemasEnumere los esquemas guardados de su organización, con los fijados primero.
Esquemasget_schemaConsulte un esquema guardado con sus propiedades, anotaciones e input_contract.
Esquemascreate_schema_from_sampleGenere y guarde automáticamente un esquema a partir de muestras revisadas, devolviendo schema_id, el contenido del esquema y los enlaces a los registros.
Esquemassave_schemaGuarda un esquema redactado directamente y devuelve su ID y su enlace.
Esquemasupdate_schemaEdite los metadatos de un esquema guardado o reemplace su schema_content completo sin realizar una llamada al LLM.
Esquemasget_schema_partConsulte solo el fragmento del esquema necesario para una edición.
Esquemasget_enum_candidatesEnumere los valores observados fuera del vocabulario actual de cada enum abierto, con recuentos de los registros de enriquecimiento recientes.
Esquemasupdate_schema_propertyEdite o elimine una propiedad por su ruta sin reemplazar el esquema completo.
Esquemasadd_schema_propertyAñada una propiedad bajo la raíz (parent_path='), una ruta de objeto o '$defs.X'.
Esquemasmove_schema_propertyMueva una propiedad a la raíz, a una ruta de objeto o a '$defs.X', conservando sus indicadores y su experiencia.
Esquemasresolve_unify_proposalResuelva una propuesta pendiente de unificación de tipos de entidad procedente de get_schema.
Esquemasnest_schema_regionMaterializar una región de entidad a partir del x-entityMap de get_schema.
Esquemaspublish_schemaPublique la copia de trabajo de un esquema vinculado a una base de datos como el contrato que utilizan el enriquecimiento y las réplicas.
Esquemasdelete_schemaElimine de forma lógica un esquema guardado por UUID.
Esquemasanalyze_sampleAnalice la ambigüedad de las propiedades de la muestra y el alcance de identidad de las relaciones antes de generar el esquema.
Esquemasanalyze_schemaAnalice la ambigüedad de las propiedades y el alcance de identidad de las relaciones de un esquema guardado, escribiendo las anotaciones en el esquema.
Enriquecimiento y fusiónstart_batch_enrichmentInicia el enriquecimiento asíncrono facturado de una lista de entidades con exactamente uno de schema_id o target_schema.
Enriquecimiento y fusiónenrich_entityEnriquezca una entidad con exactamente uno de los dos parámetros, schema_id o target_schema, y obtenga una salida estructurada, record_id, los costes y el resultado en la base de datos, si lo hay.
Enriquecimiento y fusiónretry_expertisesReintente únicamente los dominios de experiencia fallidos de un registro existente y, a continuación, actualice su salida e intente la fusión/sincronización de la ejecución.
Enriquecimiento y fusiónmerge_recordsFusione dos o más registros de la misma entidad en un nuevo registro de arbitraje.
Control de trabajosget_job_statusConsulte el estado, el progreso y el resumen final compacto de un trabajo, con los ID de los registros persistidos.
Control de trabajoscancel_jobSolicite la cancelación de un trabajo LLM pendiente, en ejecución o en pausa.
Control de trabajosanswer_job_questionReanude un trabajo en pausa con las respuestas a las preguntas devueltas durante la pausa.
Control de trabajosanswer_llm_requestEnvíe el resultado de una llamada al modelo pendiente de un trabajo delegado: un trabajo que el usuario inició con el modelo propio del cliente (el valor predeterminado de todas las herramientas de inicio, salvo que use_platform_models=true o un…
Registros y estadísticaslist_recordsEnumere los registros de su organización de forma compacta y paginada, empezando por los más recientes.
Registros y estadísticasget_recordConsulte el structured_output, el entity_input_data, los errores de validación, los veredictos de experiencia y las métricas de un registro persistido.
Registros y estadísticasget_statsConsulte los totales de registros, la tasa de éxito, los tokens y el resumen de costes de toda la organización.
Benchmarkslist_benchmark_scenariosEnumere resúmenes compactos de escenarios de benchmark y el total.
Benchmarksget_benchmark_scenarioConsulte un escenario de benchmark con los resultados de calidad, coste y velocidad por modelo.
Benchmarksget_benchmark_scenario_resultsFiltre, ordene y limite los resultados de benchmark por modelo de un escenario.
Benchmarkscreate_benchmark_scenarioCree un benchmark reutilizable con un juez de puntuación obligatorio.
Benchmarksupdate_benchmark_scenarioEdite la definición de prueba o la configuración de puntuación de un benchmark.
Benchmarksset_benchmark_referenceGuarda la referencia de oro para un benchmark de enriquecimiento o de generación de esquemas.
Benchmarksrevert_benchmark_reference_updatesDeshaga las ediciones automáticas que una pasada de puntuación aplicó a la referencia de un escenario.
Benchmarksdelete_benchmark_scenarioElimine un escenario de benchmark y sus resultados almacenados.
Benchmarksrun_benchmarkInicia la ejecución y la puntuación asíncronas facturadas de un benchmark.
Adjuntosupload_attachmentCargue bytes de archivo en base64 como material de origen reutilizable; devuelve id y requires_capability.
Adjuntosdelete_attachmentElimine de forma permanente un adjunto de su organización, incluido su archivo almacenado.
Database Synclist_database_syncsEnumere las inscripciones en bases de datos, los esquemas vinculados, las opciones y los hosts de sincronización de un esquema guardado.
Database Synclist_entity_statesExplore las filas de entidades fusionadas actuales de un esquema, no los registros de cada ejecución.
Database Synccreate_database_syncRegistre un esquema guardado para la sincronización relacional con PostgreSQL, MySQL o SQLite.
Database Syncassign_sync_hostAsigne o borre el host que aprovisiona una sincronización de base de datos.
Database Syncclassify_database_modelInicia un análisis facturado que propone claves de base de datos, tipos SQL, índices y propiedad de las relaciones en un esquema vinculado.
Database Syncdelete_database_syncElimine el registro de una base de datos y sus deltas en cola, deteniendo su flujo.
Database Syncget_database_setup_instructionsDevuelve instrucciones no secretas de instalación, emparejamiento confirmado en el navegador y ejecución para un cliente ee-database sync.
Database Syncfetch_database_deltasLea la siguiente ventana ordenada de deltas SQL y cargas canónicas de una sincronización de base de datos.
Database Syncack_database_deltasConfirme cada delta mediante up_to_id tras aplicarlo correctamente, liberando así su reserva.
Database Syncsync_records_to_databaseValide e inyecte resultados de enriquecimiento almacenados o proporcionados en la capa de entidades y en las sincronizaciones vinculadas.
IDs semánticoslist_semantic_conceptsExplore los conceptos de la organización con sus alias, recuentos de uso y facetas de tipo/modelo.
IDs semánticosget_semantic_conceptConsulte los alias, las claves de origen de identidad, los registros vinculados y los vecinos más cercanos de un concepto dentro de su propio segmento de tipo/modelo.
IDs semánticosprobe_semantic_conceptPrevisualice la resolución de identidad sin añadir un concepto ni aumentar su uso.
IDs semánticosadd_semantic_conceptAñada un concepto de identidad con uso cero, o añada texto como alias mediante alias_of.
IDs semánticosupdate_concept_aliasElimine o promueva un alias de concepto usando los ID de alias de get_semantic_concept.
IDs semánticosimport_semantic_conceptsResuelva de 1 a 1000 textos frente a un único tipo de concepto.
IDs semánticosmerge_semantic_conceptsFusione un concepto perdedor en uno ganador.
IDs semánticosdelete_semantic_conceptsElimine los conceptos seleccionados por ids, concept_types o unused_only.
IDs semánticosmigrate_semantic_embeddingsInspeccione o migre el espacio de embeddings de conceptos de la organización.
Soporte de productoask_supportHaga una pregunta a Rupert, el asistente de soporte de producto de Entity Enricher, sobre la propia aplicación: cómo funciona una función, una herramienta o un ajuste, qué significa un error_code, un límite, un estado…
Soporte de productoget_support_conversationLea uno de sus hilos de soporte con todos los turnos: sus preguntas (rol user), las respuestas de Rupert (assistant) y las respuestas de seguimiento del equipo de soporte (admin, con author_name).
Soporte de productolist_support_conversationsSus hilos de soporte, con la actividad más reciente primero, con message_count y unread_for_user (una respuesta de seguimiento del equipo de soporte que no ha leído).

Guías de flujos de trabajo, cargadas cuando se necesitan

Las instrucciones del servidor explican los flujos de trabajo disponibles; las descripciones de las herramientas explican cada llamada. Para decisiones de modelado o de recuperación, su cliente puede leer el índice de guías en enricher://docs y seleccionar una guía mediante los recursos MCP. Leer una guía no ejecuta ningún modelo. Los enlaces siguientes abren esas mismas guías en inglés en el repositorio público.

Recursos

Los recursos exponen datos de esquemas y registros, además de guías de flujo de trabajo, en Markdown. Los clientes deciden cómo descubrirlos y cargarlos; aun así, el contenido de los recursos puede consumir contexto del modelo.

Plantilla de URIDescripción
enricher://docsÍndice de las guías de flujo de trabajo, cada una disponible en su URI de recurso indicado.
enricher://schemas/{schema_id}Copia de trabajo de un esquema guardado en Markdown; use get_schema con version="published" para obtener el contrato vinculado activo.
enricher://records/{record_id}Un registro de enriquecimiento anterior representado como Markdown: metadatos + salida estructurada + errores de validación.
enricher://attachments/{attachment_id}Los bytes de un adjunto subido, servidos con su tipo de medio real: así es como un trabajo que delega sus llamadas al LLM entrega a su cliente un PDF, una imagen o un archivo de audio que este no subió.

Soporte del producto desde su cliente

Cuando una pregunta trata sobre Entity Enricher —cómo funciona una función o una herramienta, qué significa un código de error, un límite o una advertencia, por qué un resultado es como es— y las guías no la responden, las instrucciones del servidor indican al agente que pregunte a Rupert, el asistente de soporte del producto, mediante ask_support en lugar de suponer. La llamada devuelve la respuesta completa y el id del hilo que abrió; pasar eseconversation_id a la siguiente pregunta mantiene el contexto del intercambio.

Cada pregunta se descuenta de la cuota diaria de soporte de la organización, indicada comoquestions_remaining. El equipo de soporte puede responder en el hilo: la siguiente llamada a ask_support sobre ese hilo devuelve esas respuestas comonew_admin_messages, yget_support_conversation lee el hilo completo. Esos mismos hilos aparecen en el chat de soporte de la aplicación web y, para los propietarios, en la pestaña Discusiones de la página Usuarios, con una marca que indica que los abrió un agente de IA.

Gestión interactiva de la clasificación

Cuando solicita a enrich_entity que utilice un modelo de clasificación y la entidad no coincide con el tipo de esquema, la herramienta devuelve una respuesta sin error con detalles estructurados. El cliente la interpreta, le muestra el razonamiento y (previa confirmación suya) reintenta con force_after_classification_warning=true, lo que descarta el clasificador en el reintento.

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

La respuesta del MCP conserva los detalles de la clasificación para que su cliente pueda explicar la decisión antes de iniciar una nueva llamada.

La misma interactividad impulsa un segundo flujo: cuando generate_sample se ejecuta con documentos de origen, su planificador puede detenerse con preguntas de aclaración estructural. El cliente se las transmite y reanuda el trabajo con answer_job_question, ronda tras ronda, hasta generar la muestra.

Códigos de error

La mayoría de los errores de herramienta devuelven un objeto estructurado con un campo error_code para que el cliente pueda distinguir entre fallos de cuota, clasificación, tiempo de espera y proveedor. Algunas respuestas antiguas solo incluyen un campo error o message; inspeccione tanto el resultado en sí como el estado del transporte.

error_codeCuándo
invalid_requestUUID con formato incorrecto, argumentos mutuamente excluyentes (schema_id + target_schema) o la validación del cuerpo de la solicitud falló.
prompt_limit_reachedCuota de prompts diaria / semanal / mensual agotada (HTTP 402). El cuerpo incluye período, límite, usado y necesario.
insufficient_creditsLa organización tiene la facturación habilitada, pero el saldo de créditos es demasiado bajo para iniciar el trabajo (HTTP 402). El cuerpo incluye el saldo y una URL de compra.
model_limit_exceededSe solicitaron más modelos de los que permite el plan (HTTP 402). Devuelve el límite y lo solicitado.
language_limit_exceededSe solicitaron más idiomas de los que permite el plan (HTTP 402).
concurrent_job_limit_reachedDemasiados trabajos de enriquecimiento activos para esta organización. Espere o mejore el plan.
classification_warning⚡ No es un error: el clasificador previo rechazó la entidad. La respuesta incluye el contexto de clasificación para que el cliente pueda pedir confirmación al usuario y reintentar con force_after_classification_warning=true.
benchmarks_not_in_planEl plan de la organización no incluye Model Benchmarks (HTTP 403). Las herramientas de benchmark que modifican datos también comprueban el rol de propietario.
support_question_limit_reachedLa cuota diaria de preguntas de soporte de la organización está agotada (HTTP 402). El cuerpo incluye limit y used; todos los resultados de ask_support indican questions_remaining.
support_requires_userSe llamó a ask_support con una clave de acceso de organización (HTTP 403). Un hilo de soporte pertenece a una persona: inicie sesión con OAuth o con una clave API personal.
support_unavailableEl asistente de soporte no pudo responder (fallo de transmisión). La pregunta se descuenta igualmente y el hilo existe: léalo más tarde con get_support_conversation en lugar de volver a preguntar de inmediato.
web_search_undecidedSe llamó a una herramienta de inicio sin enable_web_search para un trabajo ejecutado en su modelo. Pregunte al usuario si su modelo puede usar la búsqueda web y vuelva a llamar con enable_web_search=true o false.
delegation_requires_autoUn trabajo ejecutado en su modelo encontró un modelo de plataforma explícito inyectado después del lanzamiento, como un valor predeterminado de la organización (HTTP 400). Inicie el trabajo con use_platform_models=true o elimine ese valor predeterminado.
request_not_pendinganswer_llm_request indicó una solicitud que ya fue respondida, expiró o pertenece a un trabajo que ya avanzó. Consulte get_job_status(job_id).llm_requests para ver qué está pendiente ahora.
llm_request_pendingSe llamó a answer_job_question en un trabajo pausado por solicitudes LLM delegadas, no por una pregunta. Respóndalas con answer_llm_request.
llm_request_timeoutUn trabajo que delega sus llamadas LLM no recibió respuesta a una solicitud pendiente en 15 minutos; el trabajo falló. Los trabajos delegados no tienen respuesta predeterminada.
ambiguity_check_disabledSe llamó a analyze_schema en un esquema cuya comprobación de ambigüedad está desactivada (HTTP 400). Vuelva a activarla primero mediante update_schema con ambiguity_check_enabled=true.
enrichment_timeoutEl trabajo superó timeout_seconds. Se sugiere usar menos modelos o dividir la entidad.
schema_generation_timeoutLa generación de esquemas superó timeout_seconds.
schema_generation_failedError del LLM upstream durante la generación del schema (HTTP 502).
model_output_invalidEl modelo devolvió una salida que no coincide con el esquema (HTTP 502). El cuerpo indica el modelo, la ruta de la propiedad conflictiva y retryable: true — vuelva a llamar a la herramienta o elija un modelo más potente.
cancelledEl trabajo se canceló durante su ejecución (HTTP 499).
not_foundEl ID de esquema o registro no existe en su organización.
http_errorComodín para errores HTTP sin un cuerpo de detalle estructurado.

Omisiones deliberadas

Consulte también