Server MCP per Codex e altri client AI

Codex, Cursor, VS Code con GitHub Copilot, Claude Code e Claude si connettono allo stesso server MCP di Entity Enricher. I loro agenti possono progettare schemi, eseguire l'enrichment di entità in più lingue, fondere modelli, curare identità semantiche, valutare la qualità con benchmark, sincronizzare tabelle relazionali su un database — con i modelli della piattaforma oppure con il modello del cliente quando il job delega le proprie chiamate LLM — e interpellare l'assistente di supporto del prodotto quando la domanda riguarda Entity Enricher stesso.

La validazione dello schema e l'accordo tra i modelli non garantiscono l'accuratezza fattuale né l'aggiornamento dei dati. Esaminare le fonti, gli errori e gli esiti parziali sul database. L'MCP fornisce l'accesso conversazionale; n8n e Make offrono l'automazione dei flussi di lavoro sullo stesso servizio.

Esegua i job sul modello del suo client

Per impostazione predefinita ogni tool di avvio esegue il proprio job sul suo modello (con use_platform_models=true, o indicando un modello della piattaforma, viene invece eseguito sui modelli a pagamento della piattaforma). Il job non effettua alcuna chiamata ai modelli della piattaforma e non consuma crediti: il modello dietro il suo client MCP — quello che già dispone della sua conversazione, dei suoi documenti e dei suoi tool collegati — risponde a ogni chiamata al modello del job, mentre la piattaforma continua a fare ciò in cui eccelle: costruire i prompt, applicare lo schema di output, convalidare e normalizzare ogni risposta, salvare i record e sincronizzare i database.

  1. Avvii il job senza un modello esplicito (omesso o auto), decidendoenable_web_search dove il tool lo accetta: se omesso, restituisce web_search_undecided affinché chieda prima all'utente, poiché la ricerca sarebbe la sua. Il job si mette in pausa appena la sua prima chiamata al modello è pronta.
  2. Legga llm_requests nello stato del job: ogni voce è una chiamata al modello nel formato MCP sampling/createMessage (prompt di sistema, messaggi, strumenti e toolChoice) con un purpose che indica il passaggio e una scadenza. Gli allegati binari sono referenziati come risorse enricher://attachments/{id}, mai incorporati; il testo estratto è già presente nei messaggi. Un client che ha caricato il file ne legge la propria copia, quindi un allegato non richiede mai un modello della piattaforma.
  3. Esegua la richiesta sul suo modello e restituisca il risultato conanswer_llm_request. La piattaforma lo valida rispetto allo schema esattamente come valida la risposta di un provider; una risposta rifiutata viene restituita come la stessa conversazione, con l'errore in un tool result non riuscito, da correggere e inviare di nuovo.
  4. Ripeta l'operazione fino al completamento del job. I record vengono contrassegnati con la chiave modello mcp::client a costo zero; una richiesta senza risposta fa fallire il job dopo quindici minuti.

I dettagli del protocollo e i casi limite — l'opt-out, la decisione sulla ricerca web, le richieste concorrenti, le richieste di correzione sull'arricchimento, gli allegati, i timeout — si trovano nella guida Chiamate LLM delegate elencata qui sotto.

Avvio rapido

Accesso con OAuth

OAuth consente a un client di connettersi senza chiave API. La schermata di consenso di Entity Enricher identifica il client, l'organizzazione e il ruolo concesso alla connessione. L'accesso può essere gestito o revocato in Chiavi API → App connesse.

Questi esempi utilizzano l'accesso dal browser (OAuth) e lo stesso endpoint Streamable HTTP: https://entityenricher.ai/api/mcp/, barra finale inclusa. Ogni client ha il proprio formato di configurazione.

Codex

Codex condivide le impostazioni MCP tra app, CLI ed estensione IDE tramite ~/.codex/config.toml. Il primo comando registra Entity Enricher; il comando di login apre l'accesso dal browser quando è necessaria l'autenticazione.

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

Cursor

Cursor legge i server di progetto da .cursor/mcp.json oppure i server personali da ~/.cursor/mcp.json. La voce del server remoto utilizza mcpServers; Cursor gestisce il flusso di accesso OAuth.

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

VS Code / GitHub Copilot

VS Code utilizza .vscode/mcp.json con un oggetto servers e un trasporto http esplicito. L'avvio del server rende i suoi strumenti disponibili all'agente di GitHub Copilot dopo l'autorizzazione.

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

Claude Code

Questo comando registra un server HTTP remoto in Claude Code. Il comando /mcp all'interno di Claude Code apre i controlli di connessione e autenticazione.

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

Claude / Claude Desktop

Su claude.ai e Claude Desktop, le impostazioni dei connettori offrono l'azione "Aggiungi connettore personalizzato". Il connettore utilizza l'URL del server indicato sopra e apre la schermata di autorizzazione di Entity Enricher. Questa connessione ospitata si configura tramite i connettori; claude_desktop_config.json è destinato ai server locali.

Documentazione del connettore Claude
  1. 1L'organizzazione a cui è limitata l'autorizzazione
  2. 2La connessione agisce con il proprio ruolo, mai con uno più ampio
  3. 3Revocabile in qualsiasi momento da App connesse
La schermata di consenso identifica il client richiedente, l'organizzazione e il ruolo concesso alla connessione.

Autenticazione con chiave API

Le chiavi di accesso dell'organizzazione vengono create in Impostazioni → Chiavi API con un ruolo scelto. I client possono inviare la chiave in un header X-API-Key invece di accedere con OAuth. Ad esempio, questa configurazione di Codex legge la chiave da una variabile d'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 contenere la chiave nell'ambiente del processo che esegue Codex. Cursor e VS Code accettano questo header HTTP nel proprio oggetto di configurazione headers. I riferimenti ai client indicati sopra descrivono le impostazioni supportate.

Esempio di conversazione

La stessa richiesta funziona su tutti i client: "Elenca i miei schemi Entity Enricher, poi arricchisci Sanofi utilizzando il mio schema per le aziende farmaceutiche e mostra il risultato salvato."Il client individua gli strumenti e li utilizza per selezionare uno schema ed eseguire l'arricchimento. Le richieste di conferma, la visualizzazione dell'avanzamento e l'accesso alle risorse dipendono dal client.

Strumenti

62 strumenti coprono la creazione di schemi, l'enrichment, i benchmark, il database sync, le identità semantiche e il supporto prodotto. Riutilizzano i servizi backend per validazione, fatturazione ed elaborazione. Ogni strumento espone i propri parametri supportati. Le operazioni di lunga durata (enrichment in batch, generazione di campioni, esecuzioni di benchmark) sono asincrone: lo strumento di avvio restituisce un job_id, il client interroga get_job_statuse legge i record risultanti o i risultati del benchmark. Esaminare errori ed esiti parziali prima di segnalare il successo.

CategoriaStrumentoDescrizione
Scopertalist_modelsElenca le chiavi dei modelli disponibili, le capacità nominali, le lingue, le strategie, i valori predefiniti selezionati automaticamente e i profile_limits dell'organizzazione.
Schemigenerate_sampleGenera JSON di esempio modificabile a partire da una richiesta in testo libero per la creazione di schemi.
Schemilist_schemasElenca gli schemi salvati nella propria organizzazione, con quelli fissati per primi.
Schemiget_schemaLegge uno schema salvato con le sue proprietà, annotazioni e input_contract.
Schemicreate_schema_from_sampleGenera e salva automaticamente uno schema a partire da campioni revisionati, restituendo schema_id, il contenuto dello schema e i collegamenti ai record.
Schemisave_schemaSalva uno schema redatto direttamente e ne restituisce l'ID e il link.
Schemiupdate_schemaModifica i metadati di uno schema salvato o ne sostituisce l'intero schema_content senza una chiamata LLM.
Schemiget_schema_partLegge solo il frammento di schema necessario per una modifica.
Schemiget_enum_candidatesElenca i valori osservati al di fuori del vocabolario attuale di ciascun enum aperto, con i conteggi dai record di arricchimento recenti.
Schemiupdate_schema_propertyModifica o rimuove una singola proprietà tramite percorso senza sostituire l'intero schema.
Schemiadd_schema_propertyAggiunge una proprietà sotto la radice (parent_path='), un percorso di oggetto o '$defs.X'.
Schemimove_schema_propertySposta una proprietà nella radice, in un percorso di oggetto o in '$defs.X', preservandone i flag e la competenza.
Schemiresolve_unify_proposalRisolve una proposta di unificazione di tipi di entità in attesa restituita da get_schema.
Scheminest_schema_regionMaterializza una regione di entità dalla x-entityMap di get_schema.
Schemipublish_schemaPubblica la copia di lavoro di uno schema collegato a un database come contratto usato dall'arricchimento e dalle repliche.
Schemidelete_schemaEliminare in modo soft uno schema salvato tramite UUID.
Schemianalyze_sampleAnalizza l'ambiguità delle proprietà dei campioni e la definizione dell'ambito di identità delle relazioni prima della generazione dello schema.
Schemianalyze_schemaAnalizza l'ambiguità delle proprietà e la definizione dell'ambito di identità delle relazioni di uno schema salvato, scrivendo le annotazioni nello schema.
Arricchimento e fusionestart_batch_enrichmentAvvia l'arricchimento asincrono a pagamento di un elenco di entità rispetto a esattamente uno tra schema_id e target_schema.
Arricchimento e fusioneenrich_entityArricchisce una singola entità rispetto a schema_id oppure target_schema (esattamente uno dei due), restituendo output strutturato, record_id, costi ed eventuale esito sul database.
Arricchimento e fusioneretry_expertisesRiprova solo i domini di competenza falliti di un record esistente, quindi aggiorna il suo output e tenta la fusione/sincronizzazione dell'esecuzione.
Arricchimento e fusionemerge_recordsFonde due o più record della stessa entità in un nuovo record di arbitraggio.
Controllo dei jobget_job_statusLegge lo stato, l'avanzamento e il riepilogo finale compatto di un job, con gli ID dei record salvati.
Controllo dei jobcancel_jobRichiede l'annullamento di un job LLM in attesa, in esecuzione o in pausa.
Controllo dei jobanswer_job_questionRiprende un job in pausa fornendo le risposte alle domande restituite durante la pausa.
Controllo dei jobanswer_llm_requestInvia il risultato di una chiamata al modello in attesa di un job delegato: un job avviato dall'utente sul modello del client (impostazione predefinita di ogni strumento di avvio, salvo use_platform_models=true o un…
Record e statistichelist_recordsElenca i record della propria organizzazione in forma compatta e paginata, dal più recente.
Record e statisticheget_recordLegge structured_output, entity_input_data, errori di validazione, verdetti di competenza e metriche di un record salvato.
Record e statisticheget_statsLegge i totali dei record, il tasso di successo, i token e il riepilogo dei costi a livello di organizzazione.
Benchmarklist_benchmark_scenariosElenca i riepiloghi compatti degli scenari di benchmark e il totale.
Benchmarkget_benchmark_scenarioLegge uno scenario di benchmark con i risultati di qualità, costo e velocità per modello.
Benchmarkget_benchmark_scenario_resultsFiltra, ordina e limita i risultati dei benchmark per modello di uno scenario.
Benchmarkcreate_benchmark_scenarioCrea un benchmark riutilizzabile con un giudice di valutazione obbligatorio.
Benchmarkupdate_benchmark_scenarioModifica la definizione del test o la configurazione di valutazione di un benchmark.
Benchmarkset_benchmark_referenceSalva il riferimento gold per un benchmark di arricchimento o di generazione di schemi.
Benchmarkrevert_benchmark_reference_updatesAnnulla le modifiche automatiche apportate da un ciclo di valutazione al riferimento di uno scenario.
Benchmarkdelete_benchmark_scenarioElimina uno scenario di benchmark e i relativi risultati memorizzati.
Benchmarkrun_benchmarkAvvia l'esecuzione e la valutazione asincrone a pagamento di un benchmark.
Allegatiupload_attachmentCarica i byte di un file in base64 come materiale di origine riutilizzabile; restituisce id e requires_capability.
Allegatidelete_attachmentElimina definitivamente un allegato della propria organizzazione, compreso il file archiviato.
Database Synclist_database_syncsElenca le registrazioni database, gli schemi collegati, le opzioni e gli host di sync di uno schema salvato.
Database Synclist_entity_statesEsplora le righe di entità unite correnti di uno schema, non i record per singola esecuzione.
Database Synccreate_database_syncRegistra uno schema salvato per la sincronizzazione relazionale verso PostgreSQL, MySQL o SQLite.
Database Syncassign_sync_hostAssegna o rimuove l'host che effettua il provisioning di una sincronizzazione database.
Database Syncclassify_database_modelAvvia un'analisi a pagamento che propone chiavi di database, tipi SQL, indici e titolarità delle relazioni su uno schema collegato.
Database Syncdelete_database_syncElimina la registrazione di un database e i relativi delta in coda, interrompendone il feed.
Database Syncget_database_setup_instructionsRestituisce istruzioni non riservate di installazione, di associazione confermata dal browser e di esecuzione per un client ee-database sync.
Database Syncfetch_database_deltasLegge la finestra ordinata successiva di delta SQL e payload canonici per un database sync.
Database Syncack_database_deltasConfermare ogni delta tramite up_to_id dopo l'applicazione riuscita, rilasciandone il lease.
Database Syncsync_records_to_databaseConvalida e inserisce l'output di arricchimento memorizzato o fornito nel livello delle entità e nelle sincronizzazioni collegate.
ID semanticilist_semantic_conceptsEsplora i concetti dell'organizzazione con alias, conteggi di utilizzo e facet per tipo/modello.
ID semanticiget_semantic_conceptLegge gli alias, le chiavi di origine dell'identità, i record collegati e i vicini più prossimi di un concetto all'interno della propria porzione tipo/modello.
ID semanticiprobe_semantic_conceptAnteprima della risoluzione dell'identità senza aggiungere un concetto né incrementarne l'utilizzo.
ID semanticiadd_semantic_conceptAggiunge un concetto di identità con utilizzo zero, oppure aggiunge un testo come alias tramite alias_of.
ID semanticiupdate_concept_aliasRimuove o promuove un alias di concetto usando gli ID alias restituiti da get_semantic_concept.
ID semanticiimport_semantic_conceptsRisolve 1..1000 testi rispetto a un unico tipo di concetto.
ID semanticimerge_semantic_conceptsUnisce un concetto perdente in uno vincente.
ID semanticidelete_semantic_conceptsElimina i concetti selezionati tramite ids, concept_types o unused_only.
ID semanticimigrate_semantic_embeddingsIspeziona o migra lo spazio di embedding dei concetti dell'organizzazione.
Supporto prodottoask_supportPonga a Rupert, l'assistente di supporto prodotto di Entity Enricher, una domanda sull'applicazione stessa: come funziona una funzionalità, uno strumento o un'impostazione, che cosa indicano un error_code, un limite, uno stato…
Supporto prodottoget_support_conversationLegga uno dei suoi thread di supporto con tutti i turni: le sue domande (role user), le risposte di Rupert (assistant) e i follow-up del team di supporto (admin, con author_name).
Supporto prodottolist_support_conversationsI suoi thread di supporto, dall'attività più recente, con message_count e unread_for_user (un follow-up del team di supporto non ancora letto).

Guide ai flussi di lavoro, caricate all'occorrenza

Le istruzioni del server descrivono i flussi di lavoro disponibili; le descrizioni degli strumenti spiegano le singole chiamate. Per le decisioni di modellazione o il ripristino, il client può leggere l'indice delle guide su enricher://docs e selezionare una guida tramite le risorse MCP. La lettura di una guida non esegue alcun modello. I link qui sotto aprono le stesse guide in inglese nel repository pubblico.

Risorse

Le risorse espongono i dati di schemi e record, oltre alle guide ai flussi di lavoro, in formato Markdown. I client scelgono come individuarle e caricarle; il contenuto delle risorse può comunque consumare il contesto del modello.

Template URIDescrizione
enricher://docsIndice delle guide ai flussi di lavoro, ciascuna disponibile all'URI di risorsa indicato.
enricher://schemas/{schema_id}Copia di lavoro di uno schema salvato in formato Markdown; utilizzare get_schema con version="published" per il contratto collegato attivo.
enricher://records/{record_id}Un record di arricchimento passato rappresentato come Markdown — metadati + output strutturato + errori di validazione.
enricher://attachments/{attachment_id}I byte di un allegato caricato, serviti con il loro tipo di media effettivo: è così che un job che delega le proprie chiamate LLM consegna al suo client un file PDF, immagine o audio che il client non ha caricato direttamente.

Supporto prodotto dal proprio client

Quando una domanda riguarda Entity Enricher stesso — come funziona una funzionalità o uno strumento, cosa significa un codice di errore, un limite o un avviso, perché un risultato si presenta in un certo modo — e le guide non forniscono una risposta, le istruzioni del server indicano all'agente di rivolgersi a Rupert, l'assistente di supporto del prodotto, con ask_support anziché tirare a indovinare. La chiamata restituisce la risposta completa e l'id del thread aperto; passando taleconversation_id alla domanda successiva si mantiene il contesto dello scambio.

Ogni domanda viene conteggiata nella quota giornaliera di supporto dell'organizzazione, riportata comequestions_remaining. Il team di supporto può rispondere nel thread: la successiva ask_support sullo stesso thread restituisce tali risposte comenew_admin_messages, mentreget_support_conversation legge un intero thread. Gli stessi thread compaiono nella chat di supporto dell'app web e, per i proprietari, nella scheda Discussioni della pagina Utenti, contrassegnati come aperti da un agente AI.

Gestione interattiva della classificazione

Quando si richiede a enrich_entity di utilizzare un modello di classificazione e l'entità non corrisponde al tipo di schema, lo strumento restituisce una risposta non di errore con dettagli strutturati. Il client la interpreta, mostra all'utente il ragionamento e, previa conferma, riprova con force_after_classification_warning=true — che esclude il classificatore nel nuovo tentativo.

{
  "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 risposta MCP conserva i dettagli della classificazione, così il client può spiegare la decisione prima di avviare una nuova chiamata.

La stessa interattività alimenta un secondo flusso: quando generate_sample viene eseguito con documenti di origine, il relativo planner può sospendersi ponendo domande di chiarimento sulla struttura. Il client le inoltra all'utente e riprende il job con answer_job_question — round dopo round, fino alla generazione del campione.

Codici di errore

La maggior parte degli errori degli strumenti restituisce un oggetto strutturato con un campo error_code, così il client può distinguere gli errori di quota, classificazione, timeout e provider. Alcune risposte meno recenti contengono solo un campo error o message; esaminare il risultato effettivo oltre allo stato del trasporto.

error_codeQuando
invalid_requestUUID malformato, argomenti mutuamente esclusivi (schema_id + target_schema) o convalida del corpo della richiesta non riuscita.
prompt_limit_reachedQuota di prompt giornaliera / settimanale / mensile esaurita (HTTP 402). Il corpo include periodo, limite, utilizzati e necessari.
insufficient_creditsL'org ha la fatturazione attiva ma il saldo dei crediti è troppo basso per avviare il lavoro (HTTP 402). Il corpo include il saldo e un URL di acquisto.
model_limit_exceededRichiesti più modelli di quanti ne consenta il piano (HTTP 402). Riporta il limite e la quantità richiesta.
language_limit_exceededRichieste più lingue di quante ne consenta il piano (HTTP 402).
concurrent_job_limit_reachedTroppi processi di arricchimento attivi per questa organizzazione. Attenda o aggiorni il piano.
classification_warning⚡ Non è un errore: il classificatore preliminare ha rifiutato l'entità. La risposta include il contesto di classificazione, così il client può chiedere all'utente di confermare e riprovare con force_after_classification_warning=true.
benchmarks_not_in_planIl piano dell'organizzazione non include i Benchmark dei modelli (HTTP 403). Gli strumenti di benchmark che effettuano modifiche verificano anche il ruolo di proprietario.
support_question_limit_reachedLa quota giornaliera di domande di supporto dell'organizzazione è esaurita (HTTP 402). Il body include limit e used; ogni risultato di ask_support riporta questions_remaining.
support_requires_userask_support è stato chiamato con una chiave di accesso dell'organizzazione (HTTP 403). Un thread di supporto appartiene a una persona: effettuare l'accesso con OAuth o con una chiave API personale.
support_unavailableL'assistente di supporto non è riuscito a rispondere (errore di inoltro). La domanda viene comunque conteggiata e il thread esiste: leggerlo in seguito con get_support_conversation anziché ripetere subito la domanda.
web_search_undecidedUn tool di avvio è stato chiamato senza enable_web_search per un job in esecuzione sul suo modello. Chieda all'utente se il suo modello può utilizzare la ricerca web, poi richiami con enable_web_search=true o false.
delegation_requires_autoUn job in esecuzione sul suo modello ha incontrato un modello della piattaforma esplicito, inserito dopo l'avvio, come un valore predefinito dell'organizzazione (HTTP 400). Avvii il job con use_platform_models=true oppure rimuova tale valore predefinito.
request_not_pendinganswer_llm_request ha indicato una richiesta già risposta, scaduta o appartenente a un job che ha proseguito. Consulti get_job_status(job_id).llm_requests per sapere quali richieste sono attualmente in attesa.
llm_request_pendinganswer_job_question è stato invocato su un job in pausa su richieste LLM delegate, non su una domanda. Risponda a queste ultime con answer_llm_request.
llm_request_timeoutUn job che delega le proprie chiamate LLM non ha ricevuto risposta a una richiesta in attesa entro 15 minuti; il job è fallito. I job delegati non prevedono una risposta predefinita.
ambiguity_check_disabledanalyze_schema è stato chiamato su uno schema il cui controllo di ambiguità è disattivato (HTTP 400). Riattivarlo prima tramite update_schema con ambiguity_check_enabled=true.
enrichment_timeoutIl job ha superato timeout_seconds. Suggeriamo di ridurre i modelli o di suddividere l'entity.
schema_generation_timeoutLa generazione dello schema ha superato timeout_seconds.
schema_generation_failedErrore LLM upstream durante la generazione dello schema (HTTP 502).
model_output_invalidIl model ha restituito un output non conforme allo schema (HTTP 502). Il corpo della risposta indica il model, il percorso della proprietà non valida e retryable: true — richiami lo strumento oppure scelga un model più potente.
cancelledIl job è stato annullato durante l'esecuzione (HTTP 499).
not_foundLo schema o l'ID del record non esiste nella vostra organizzazione.
http_errorGestione generica per gli errori HTTP privi di un corpo di dettaglio strutturato.

Omissioni deliberate

Vedi anche