Servidor MCP para o Codex e outros clientes de IA

O Codex, o Cursor, o VS Code com GitHub Copilot, o Claude Code e o Claude ligam-se ao mesmo servidor MCP do Entity Enricher. Os seus agentes podem desenhar esquemas, enriquecer entidades em várias línguas, fundir modelos, curar identidades semânticas, avaliar a qualidade com benchmarks, sincronizar tabelas relacionais com uma base de dados — nos modelos da plataforma ou no modelo do próprio cliente, quando o trabalho delega as suas chamadas LLM — e perguntar ao assistente de suporte do produto quando a questão é sobre o próprio Entity Enricher.

A validação do esquema e a concordância entre modelos não garantem a exatidão factual nem a atualidade dos dados. Analise as fontes, as falhas e os resultados parciais na base de dados. O MCP disponibiliza acesso conversacional; o n8n e o Make disponibilizam automação de fluxos de trabalho sobre o mesmo serviço.

Execute tarefas no modelo do seu cliente

Por predefinição, todas as ferramentas de início executam a sua tarefa no seu próprio modelo (com use_platform_models=true, ou indicando um modelo de plataforma, passa a correr nos modelos faturados da plataforma). A tarefa não faz nenhuma chamada a modelos da plataforma e não gasta créditos: o modelo por trás do seu cliente MCP — o que já tem a sua conversa, os seus documentos e as suas ferramentas ligadas — responde a todas as chamadas de modelo da tarefa, e a plataforma fica com aquilo em que é boa: construir os prompts, aplicar o esquema de saída, validar e normalizar cada resposta, guardar os registos e sincronizar as bases de dados.

  1. Inicie a tarefa sem modelo explícito (omitido ou auto), decidindoenable_web_search onde a ferramenta o aceita: se for omitido, devolve web_search_undecided para que pergunte primeiro ao utilizador, já que a pesquisa seria sua. A tarefa fica em pausa assim que a sua primeira chamada de modelo estiver pronta.
  2. Leia llm_requests no estado da tarefa: cada entrada corresponde a uma chamada ao modelo no formato MCP sampling/createMessage — prompt de sistema, mensagens, ferramentas e toolChoice — com um purpose que identifica o passo e um prazo. Os anexos binários são referenciados como recursosenricher://attachments/{id}, nunca incluídos diretamente; o texto extraído já está nas mensagens. Um cliente que carregou o ficheiro lê a sua própria cópia, pelo que um anexo nunca exige um modelo da plataforma.
  3. Execute o pedido no seu próprio modelo e devolva o resultado comanswer_llm_request. A plataforma valida-o em relação ao esquema exatamente como valida a resposta de um fornecedor; uma resposta rejeitada regressa como a mesma conversa, com o erro num tool result falhado, para corrigir e responder de novo.
  4. Repita até a tarefa terminar. Os registos são marcados com a chave de modelo mcp::client a custo zero; um pedido sem resposta faz a tarefa falhar após quinze minutos.

Os detalhes do protocolo e os casos-limite — a exclusão, a decisão sobre a pesquisa web, os pedidos concorrentes, os pedidos de correção no enriquecimento, os anexos, os tempos de espera — estão no guia Chamadas LLM delegadas indicado abaixo.

Início rápido

Início de sessão com OAuth

O OAuth permite que um cliente se ligue sem chave de API. O ecrã de consentimento do Entity Enricher identifica o cliente, a organização e a função concedida à ligação. O acesso pode ser gerido ou revogado em Chaves de API → Aplicações ligadas.

Estes exemplos utilizam o início de sessão no navegador (OAuth) e o mesmo endpoint Streamable HTTP: https://entityenricher.ai/api/mcp/, incluindo a barra final. Cada cliente tem o seu próprio formato de configuração.

Codex

O Codex partilha as definições MCP entre a aplicação, a CLI e a extensão de IDE através de ~/.codex/config.toml. O primeiro comando regista o Entity Enricher; o comando de início de sessão abre a autenticação no navegador sempre que esta é necessária.

Codex CLI
codex mcp add entity-enricher --url https://entityenricher.ai/api/mcp/
codex mcp login entity-enricher
Documentação do Codex

Cursor

O Cursor lê os servidores do projeto em .cursor/mcp.json ou os servidores pessoais em ~/.cursor/mcp.json. A entrada do servidor remoto utiliza mcpServers; o Cursor trata do fluxo de início de sessão OAuth.

.cursor/mcp.json
{
  "mcpServers": {
    "entity-enricher": {
      "url": "https://entityenricher.ai/api/mcp/"
    }
  }
}
Documentação do Cursor

VS Code / GitHub Copilot

O VS Code utiliza .vscode/mcp.json com um objeto servers e um transporte http explícito. Ao iniciar o servidor, as suas ferramentas ficam disponíveis para o agente do GitHub Copilot após a autorização.

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

Claude Code

Este comando regista um servidor HTTP remoto no Claude Code. O comando /mcp dentro do Claude Code abre os controlos de ligação e de autenticação.

Claude Code CLI
claude mcp add --transport http entity-enricher https://entityenricher.ai/api/mcp/
Documentação do Claude Code

Claude / Claude Desktop

No claude.ai e no Claude Desktop, as definições de Conectores oferecem a ação "Adicionar conector personalizado". O conector utiliza o URL do servidor indicado acima e abre o ecrã de autorização do Entity Enricher. Esta ligação alojada é configurada através de Conectores; o ficheiro claude_desktop_config.json destina-se a servidores locais.

Documentação do conector Claude
  1. 1A organização a que a autorização se aplica
  2. 2A ligação atua com a sua própria função, nunca com uma mais abrangente
  3. 3Revogável a qualquer momento em Aplicações Ligadas
O ecrã de consentimento identifica o cliente requerente, a organização e a função concedida à ligação.

Autenticação por chave de API

As chaves de acesso da organização são criadas em Definições → Chaves de API com uma função à escolha. Os clientes podem enviar a chave num cabeçalho X-API-Key em vez de iniciarem sessão com OAuth. Por exemplo, esta configuração do Codex lê a chave a partir de uma variável de ambiente:

~/.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 deve conter a chave no ambiente do processo que executa o Codex. O Cursor e o VS Code aceitam este cabeçalho HTTP no respetivo objeto de configuração headers. As referências de cliente acima descrevem as definições suportadas.

Exemplo de conversa

O mesmo pedido funciona em qualquer cliente: "Liste os meus schemas do Entity Enricher, depois enriqueça a Sanofi com o meu schema de empresa farmacêutica e mostre o resultado guardado."O cliente descobre as ferramentas e utiliza-as para selecionar um schema e executar o enriquecimento. Os pedidos de confirmação, a apresentação do progresso e o acesso aos recursos dependem do cliente.

Ferramentas

As 62 ferramentas abrangem a criação de esquemas, enriquecimento, benchmarks, database sync, identidades semânticas e suporte ao produto. Reutilizam serviços de backend para validação, faturação e processamento. Cada ferramenta expõe os seus próprios parâmetros suportados. O trabalho de longa duração (enriquecimento em lote, geração de amostras, execuções de benchmark) é assíncrono: a ferramenta de arranque devolve um job_id, o cliente consulta get_job_statuse lê os registos resultantes ou os resultados do benchmark. Inspecione as falhas e os resultados parciais antes de comunicar sucesso.

CategoriaFerramentaDescrição
Descobertalist_modelsListe as chaves de modelo disponíveis, as capacidades nominais, os idiomas, as estratégias, as predefinições selecionadas automaticamente e os profile_limits da organização.
Esquemasgenerate_sampleGere JSON de amostra editável a partir de um pedido em texto livre para a criação de esquemas.
Esquemaslist_schemasListe os schemas guardados na sua organização, começando pelos fixados.
Esquemasget_schemaConsulte um schema guardado com as suas propriedades, anotações e input_contract.
Esquemascreate_schema_from_sampleGere e guarde automaticamente um esquema a partir de amostras revistas, devolvendo schema_id, o conteúdo do esquema e as ligações aos registos.
Esquemassave_schemaGuarde um esquema escrito diretamente e devolva o respetivo ID e link.
Esquemasupdate_schemaEdite os metadados de um esquema guardado ou substitua todo o seu schema_content sem uma chamada ao LLM.
Esquemasget_schema_partLeia apenas o fragmento de schema necessário para uma edição.
Esquemasget_enum_candidatesListe os valores observados fora do vocabulário atual de cada enum aberto, com contagens dos registos de enriquecimento recentes.
Esquemasupdate_schema_propertyEdite ou remova uma propriedade por caminho sem substituir o esquema completo.
Esquemasadd_schema_propertyAdicione uma propriedade sob a raiz (parent_path='), num caminho de objeto ou em '$defs.X'.
Esquemasmove_schema_propertyMova uma propriedade para a raiz, para um caminho de objeto ou para '$defs.X', preservando as suas flags e a sua especialidade.
Esquemasresolve_unify_proposalResolva uma proposta pendente de unificação de tipos de entidade proveniente de get_schema.
Esquemasnest_schema_regionMaterializar uma região de entidade a partir do x-entityMap de get_schema.
Esquemaspublish_schemaPublique a cópia de trabalho de um schema associado a uma base de dados como o contrato usado pelo enriquecimento e pelas réplicas.
Esquemasdelete_schemaElimine (soft delete) um esquema guardado por UUID.
Esquemasanalyze_sampleAnalise a ambiguidade das propriedades da amostra e o âmbito de identidade das relações antes da geração do esquema.
Esquemasanalyze_schemaAnalise a ambiguidade das propriedades e o âmbito de identidade das relações de um esquema guardado, escrevendo anotações no esquema.
Enriquecimento e fusãostart_batch_enrichmentInicie o enriquecimento assíncrono faturado de uma lista de entidades com exatamente um de schema_id ou target_schema.
Enriquecimento e fusãoenrich_entityEnriqueça uma entidade com exatamente um de schema_id ou target_schema, devolvendo saída estruturada, record_id, custos e qualquer resultado na base de dados.
Enriquecimento e fusãoretry_expertisesRepita apenas os domínios de especialidade falhados de um registo existente, atualizando depois o respetivo output e tentando a fusão/sincronização da execução.
Enriquecimento e fusãomerge_recordsFunda dois ou mais registos da mesma entidade num novo registo de arbitragem.
Controlo de tarefasget_job_statusConsulte o estado, o progresso e o resumo final compacto de uma tarefa, com os IDs dos registos persistidos.
Controlo de tarefascancel_jobSolicite o cancelamento de uma tarefa LLM pendente, em execução ou em pausa.
Controlo de tarefasanswer_job_questionRetome uma tarefa em pausa com as respostas às perguntas devolvidas durante a pausa.
Controlo de tarefasanswer_llm_requestSubmeta o resultado de uma chamada de modelo pendente de uma tarefa delegada: uma tarefa que o utilizador iniciou no modelo do próprio cliente (a predefinição de todas as ferramentas de início, exceto se use_platform_models=true ou um…
Registos e estatísticaslist_recordsListe os registos da sua organização de forma compacta e paginada, dos mais recentes para os mais antigos.
Registos e estatísticasget_recordConsulte o structured_output, o entity_input_data, os erros de validação, os veredictos de especialidade e as métricas de um registo persistido.
Registos e estatísticasget_statsConsulte os totais de registos, a taxa de sucesso, os tokens e o resumo de custos de toda a organização.
Benchmarkslist_benchmark_scenariosListe resumos compactos dos cenários de benchmark e o total.
Benchmarksget_benchmark_scenarioConsulte um cenário de benchmark com os resultados de qualidade, custo e velocidade por modelo.
Benchmarksget_benchmark_scenario_resultsFiltre, ordene e limite os resultados de benchmark por modelo de um cenário.
Benchmarkscreate_benchmark_scenarioCrie um benchmark reutilizável com um avaliador de pontuação obrigatório.
Benchmarksupdate_benchmark_scenarioEdite a definição de teste ou a configuração de pontuação de um benchmark.
Benchmarksset_benchmark_referenceGuarde a referência gold de um benchmark de enriquecimento ou de geração de esquemas.
Benchmarksrevert_benchmark_reference_updatesAnule as edições automáticas que uma passagem de pontuação fez à referência de um cenário.
Benchmarksdelete_benchmark_scenarioElimine um cenário de benchmark e os respetivos resultados guardados.
Benchmarksrun_benchmarkInicie a execução e a pontuação assíncronas e faturadas de um benchmark.
Anexosupload_attachmentCarregue os bytes de um ficheiro em base64 como material de origem reutilizável; devolve id e requires_capability.
Anexosdelete_attachmentElimine permanentemente um anexo da sua organização, incluindo o respetivo ficheiro armazenado.
Database Synclist_database_syncsListe as inscrições em base de dados, os schemas associados, as opções e os anfitriões de sincronização de um schema guardado.
Database Synclist_entity_statesConsulte as linhas de entidades combinadas atuais de um esquema, e não os registos por execução.
Database Synccreate_database_syncRegiste um schema guardado para sincronização relacional com PostgreSQL, MySQL ou SQLite.
Database Syncassign_sync_hostAtribua ou remova o anfitrião que aprovisiona um Database Sync.
Database Syncclassify_database_modelInicie uma análise faturada que propõe chaves de base de dados, tipos SQL, índices e a titularidade das relações num esquema associado.
Database Syncdelete_database_syncElimine um registo de base de dados e os respetivos deltas em fila, interrompendo o seu fluxo.
Database Syncget_database_setup_instructionsDevolve instruções não secretas de instalação, de emparelhamento confirmado no browser e de execução para um cliente de ee-database sync.
Database Syncfetch_database_deltasLeia a janela ordenada seguinte de deltas SQL e de payloads canónicos de uma sincronização de base de dados.
Database Syncack_database_deltasConfirme cada delta até up_to_id após a aplicação bem-sucedida, libertando a respetiva lease.
Database Syncsync_records_to_databaseValide e injete resultados de enriquecimento armazenados ou fornecidos na camada de entidades e nas sincronizações associadas.
IDs semânticoslist_semantic_conceptsConsulte os conceitos da organização com aliases, contagens de utilização e facetas de tipo/modelo.
IDs semânticosget_semantic_conceptConsulte os aliases, as chaves de identidade de origem, os registos associados e os vizinhos mais próximos de um conceito dentro da sua própria fatia de tipo/modelo.
IDs semânticosprobe_semantic_conceptPré-visualize a resolução de identidade sem adicionar um conceito nem aumentar a respetiva utilização.
IDs semânticosadd_semantic_conceptAdicione um conceito de identidade com utilização zero, ou adicione texto como alias através de alias_of.
IDs semânticosupdate_concept_aliasRemova ou promova um alias de conceito usando os IDs de alias obtidos em get_semantic_concept.
IDs semânticosimport_semantic_conceptsResolva 1..1000 textos face a um tipo de conceito.
IDs semânticosmerge_semantic_conceptsFunda um conceito perdedor num conceito vencedor.
IDs semânticosdelete_semantic_conceptsElimine conceitos selecionados por ids, concept_types ou unused_only.
IDs semânticosmigrate_semantic_embeddingsInspecione ou migre o espaço de embeddings de conceitos da organização.
Suporte ao produtoask_supportColoque uma questão ao Rupert, o assistente de suporte ao produto do Entity Enricher, sobre a própria aplicação: como funciona uma funcionalidade, uma ferramenta ou uma definição, o que significa um error_code, um limite, um estado…
Suporte ao produtoget_support_conversationLeia um dos seus tópicos de suporte com todos os turnos: as suas perguntas (role user), as respostas do Rupert (assistant) e as respostas de seguimento da equipa de suporte (admin, com author_name).
Suporte ao produtolist_support_conversationsOs seus tópicos de suporte, com a atividade mais recente primeiro, com message_count e unread_for_user (uma resposta de seguimento da equipa de suporte que ainda não leu).

Guias de fluxos de trabalho, carregados quando necessário

As instruções do servidor explicam os fluxos de trabalho disponíveis; as descrições das ferramentas explicam cada chamada. Para decisões de modelação ou de recuperação, o seu cliente pode consultar o índice de guias em enricher://docs e selecionar um guia através dos recursos MCP. Ler um guia não executa qualquer modelo. As ligações abaixo abrem os mesmos guias, em inglês, no repositório público.

Recursos

Os recursos expõem dados de schema e de registos, bem como guias de fluxo de trabalho, em Markdown. Os clientes escolhem como os descobrir e carregar; ainda assim, o conteúdo dos recursos pode consumir contexto do modelo.

Modelo de URIDescrição
enricher://docsÍndice dos guias de fluxo de trabalho, cada um disponível no URI de recurso indicado.
enricher://schemas/{schema_id}Uma cópia de trabalho de um esquema guardado em Markdown; utilize get_schema com version="published" para obter o contrato ativo associado.
enricher://records/{record_id}Um registo de enriquecimento anterior apresentado em Markdown — metadados + saída estruturada + erros de validação.
enricher://attachments/{attachment_id}Os bytes de um anexo carregado, servidos com o seu tipo de media real — é assim que uma tarefa que delega as suas chamadas ao LLM entrega ao seu cliente um ficheiro PDF, de imagem ou de áudio que este não carregou.

Suporte do produto a partir do seu cliente

Quando uma questão é sobre o próprio Entity Enricher — como funciona uma funcionalidade ou uma ferramenta, o que significa um código de erro, um limite ou um aviso, porque é que um resultado tem determinado aspeto — e os guias não respondem, as instruções do servidor dizem ao agente para perguntar ao Rupert, o assistente de suporte do produto, com ask_support em vez de adivinhar. A chamada devolve a resposta completa e o id do tópico que abriu; passar esseconversation_id à pergunta seguinte mantém o contexto da troca.

Cada pergunta é descontada da quota diária de suporte da organização, indicada emquestions_remaining. A equipa de suporte pode responder no tópico: o próximo ask_support nesse tópico devolve essas respostas emnew_admin_messages, eget_support_conversation lê um tópico completo. Os mesmos tópicos aparecem no chat de suporte da aplicação web e, para os proprietários, no separador Discussões da página Utilizadores, marcados como abertos por um agente de IA.

Tratamento interativo de classificação

Quando pede a enrich_entity para usar um modelo de classificação e a entity não corresponde ao tipo do schema, a ferramenta devolve uma resposta sem erro com detalhes estruturados. O cliente lê-a, apresenta-lhe o raciocínio e (após a sua confirmação) tenta novamente com force_after_classification_warning=true — o que dispensa o classificador nessa nova tentativa.

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

A resposta do MCP preserva os detalhes da classificação, para que o seu cliente possa explicar a decisão antes de iniciar uma nova chamada.

A mesma interatividade suporta um segundo fluxo: quando generate_sample é executado com documentos de origem, o respetivo planeador pode pausar com perguntas de clarificação estrutural. O cliente encaminha-as para você e retoma a tarefa com answer_job_question — ronda após ronda, até a amostra ser gerada.

Códigos de erro

A maioria dos erros de ferramentas devolve um objeto estruturado com um campo error_code, para que o cliente consiga distinguir falhas de quota, de classificação, de tempo limite e do fornecedor. Algumas respostas mais antigas incluem apenas um campo error ou message; inspecione o resultado propriamente dito, além do estado do transporte.

error_codeQuando
invalid_requestUUID malformado, argumentos mutuamente exclusivos (schema_id + target_schema) ou falha na validação do corpo do pedido.
prompt_limit_reachedQuota de prompts diária / semanal / mensal esgotada (HTTP 402). O corpo inclui período, limite, utilizado e necessário.
insufficient_creditsA org tem a faturação ativada, mas o saldo de credits é demasiado baixo para iniciar o trabalho (HTTP 402). O corpo inclui o saldo e um URL de compra.
model_limit_exceededForam pedidos mais modelos do que o plano permite (HTTP 402). Devolve o limite + o solicitado.
language_limit_exceededForam pedidos mais idiomas do que o plano permite (HTTP 402).
concurrent_job_limit_reachedDemasiadas tarefas de enriquecimento ativas para esta organização. Aguarde ou atualize o plano.
classification_warning⚡ Não é um erro: o classificador prévio rejeitou a entidade. A resposta inclui o contexto de classificação para que o cliente possa pedir confirmação ao utilizador e tentar novamente com force_after_classification_warning=true.
benchmarks_not_in_planO plano da organização não inclui os Benchmarks de Modelos (HTTP 403). As ferramentas de benchmark que alteram dados verificam também o papel de proprietário.
support_question_limit_reachedA quota diária de perguntas de suporte da organização está esgotada (HTTP 402). O corpo inclui limit e used; cada resultado de ask_support indica questions_remaining.
support_requires_userask_support foi chamada com uma chave de acesso de organização (HTTP 403). Um tópico de suporte pertence a uma pessoa: inicie sessão com OAuth ou com uma chave de API pessoal.
support_unavailableO assistente de suporte não conseguiu responder (falha de encaminhamento). A pergunta continua a ser contabilizada e o tópico existe: leia-o mais tarde com get_support_conversation em vez de perguntar outra vez de imediato.
web_search_undecidedUma ferramenta de início foi chamada sem enable_web_search para uma tarefa a correr no seu modelo. Pergunte ao utilizador se o seu modelo pode usar a pesquisa web e volte a chamá-la com enable_web_search=true ou false.
delegation_requires_autoUma tarefa a correr no seu modelo encontrou um modelo de plataforma explícito injetado após o início, como uma predefinição da organização (HTTP 400). Inicie a tarefa com use_platform_models=true ou elimine essa predefinição.
request_not_pendinganswer_llm_request indicou um pedido que já foi respondido, expirou ou pertence a uma tarefa que entretanto avançou. Consulte get_job_status(job_id).llm_requests para saber o que está pendente agora.
llm_request_pendinganswer_job_question foi chamado numa tarefa pausada em pedidos LLM delegados, não numa pergunta. Responda-lhes com answer_llm_request.
llm_request_timeoutUma tarefa que delega as suas chamadas LLM não recebeu resposta a um pedido pendente no prazo de 15 minutos; a tarefa falhou. As tarefas delegadas não têm resposta predefinida.
ambiguity_check_disabledanalyze_schema foi chamado num esquema cuja verificação de ambiguidade está desativada (HTTP 400). Reative-a primeiro através de update_schema com ambiguity_check_enabled=true.
enrichment_timeoutA tarefa excedeu timeout_seconds. Sugira menos models ou dividir a entity.
schema_generation_timeoutA geração de esquemas excedeu o timeout_seconds.
schema_generation_failedErro do LLM a montante durante a geração do schema (HTTP 502).
model_output_invalidO modelo devolveu um resultado que não corresponde ao schema (HTTP 502). O corpo indica o modelo, o caminho da propriedade em causa e retryable: true — chame novamente a ferramenta ou escolha um modelo mais forte.
cancelledA tarefa foi cancelada a meio da execução (HTTP 499).
not_foundO ID do esquema ou do registo não existe na sua organização.
http_errorGenérico para erros HTTP sem um corpo de detalhe estruturado.

Omissões deliberadas

Ver também