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.
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.
enable_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.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.answer_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.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.
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 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 mcp add entity-enricher --url https://entityenricher.ai/api/mcp/
codex mcp login entity-enricherCursor 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.
{
"mcpServers": {
"entity-enricher": {
"url": "https://entityenricher.ai/api/mcp/"
}
}
}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.
{
"servers": {
"entity-enricher": {
"type": "http",
"url": "https://entityenricher.ai/api/mcp/"
}
}
}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 mcp add --transport http entity-enricher https://entityenricher.ai/api/mcp/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.
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:
[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.
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.
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.
| Categoria | Strumento | Descrizione |
|---|---|---|
| Scoperta | list_models | Elenca le chiavi dei modelli disponibili, le capacità nominali, le lingue, le strategie, i valori predefiniti selezionati automaticamente e i profile_limits dell'organizzazione. |
| Schemi | generate_sample | Genera JSON di esempio modificabile a partire da una richiesta in testo libero per la creazione di schemi. |
| Schemi | list_schemas | Elenca gli schemi salvati nella propria organizzazione, con quelli fissati per primi. |
| Schemi | get_schema | Legge uno schema salvato con le sue proprietà, annotazioni e input_contract. |
| Schemi | create_schema_from_sample | Genera e salva automaticamente uno schema a partire da campioni revisionati, restituendo schema_id, il contenuto dello schema e i collegamenti ai record. |
| Schemi | save_schema | Salva uno schema redatto direttamente e ne restituisce l'ID e il link. |
| Schemi | update_schema | Modifica i metadati di uno schema salvato o ne sostituisce l'intero schema_content senza una chiamata LLM. |
| Schemi | get_schema_part | Legge solo il frammento di schema necessario per una modifica. |
| Schemi | get_enum_candidates | Elenca i valori osservati al di fuori del vocabolario attuale di ciascun enum aperto, con i conteggi dai record di arricchimento recenti. |
| Schemi | update_schema_property | Modifica o rimuove una singola proprietà tramite percorso senza sostituire l'intero schema. |
| Schemi | add_schema_property | Aggiunge una proprietà sotto la radice (parent_path='), un percorso di oggetto o '$defs.X'. |
| Schemi | move_schema_property | Sposta una proprietà nella radice, in un percorso di oggetto o in '$defs.X', preservandone i flag e la competenza. |
| Schemi | resolve_unify_proposal | Risolve una proposta di unificazione di tipi di entità in attesa restituita da get_schema. |
| Schemi | nest_schema_region | Materializza una regione di entità dalla x-entityMap di get_schema. |
| Schemi | publish_schema | Pubblica la copia di lavoro di uno schema collegato a un database come contratto usato dall'arricchimento e dalle repliche. |
| Schemi | delete_schema | Eliminare in modo soft uno schema salvato tramite UUID. |
| Schemi | analyze_sample | Analizza l'ambiguità delle proprietà dei campioni e la definizione dell'ambito di identità delle relazioni prima della generazione dello schema. |
| Schemi | analyze_schema | Analizza l'ambiguità delle proprietà e la definizione dell'ambito di identità delle relazioni di uno schema salvato, scrivendo le annotazioni nello schema. |
| Arricchimento e fusione | start_batch_enrichment | Avvia l'arricchimento asincrono a pagamento di un elenco di entità rispetto a esattamente uno tra schema_id e target_schema. |
| Arricchimento e fusione | enrich_entity | Arricchisce 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 fusione | retry_expertises | Riprova solo i domini di competenza falliti di un record esistente, quindi aggiorna il suo output e tenta la fusione/sincronizzazione dell'esecuzione. |
| Arricchimento e fusione | merge_records | Fonde due o più record della stessa entità in un nuovo record di arbitraggio. |
| Controllo dei job | get_job_status | Legge lo stato, l'avanzamento e il riepilogo finale compatto di un job, con gli ID dei record salvati. |
| Controllo dei job | cancel_job | Richiede l'annullamento di un job LLM in attesa, in esecuzione o in pausa. |
| Controllo dei job | answer_job_question | Riprende un job in pausa fornendo le risposte alle domande restituite durante la pausa. |
| Controllo dei job | answer_llm_request | Invia 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 statistiche | list_records | Elenca i record della propria organizzazione in forma compatta e paginata, dal più recente. |
| Record e statistiche | get_record | Legge structured_output, entity_input_data, errori di validazione, verdetti di competenza e metriche di un record salvato. |
| Record e statistiche | get_stats | Legge i totali dei record, il tasso di successo, i token e il riepilogo dei costi a livello di organizzazione. |
| Benchmark | list_benchmark_scenarios | Elenca i riepiloghi compatti degli scenari di benchmark e il totale. |
| Benchmark | get_benchmark_scenario | Legge uno scenario di benchmark con i risultati di qualità, costo e velocità per modello. |
| Benchmark | get_benchmark_scenario_results | Filtra, ordina e limita i risultati dei benchmark per modello di uno scenario. |
| Benchmark | create_benchmark_scenario | Crea un benchmark riutilizzabile con un giudice di valutazione obbligatorio. |
| Benchmark | update_benchmark_scenario | Modifica la definizione del test o la configurazione di valutazione di un benchmark. |
| Benchmark | set_benchmark_reference | Salva il riferimento gold per un benchmark di arricchimento o di generazione di schemi. |
| Benchmark | revert_benchmark_reference_updates | Annulla le modifiche automatiche apportate da un ciclo di valutazione al riferimento di uno scenario. |
| Benchmark | delete_benchmark_scenario | Elimina uno scenario di benchmark e i relativi risultati memorizzati. |
| Benchmark | run_benchmark | Avvia l'esecuzione e la valutazione asincrone a pagamento di un benchmark. |
| Allegati | upload_attachment | Carica i byte di un file in base64 come materiale di origine riutilizzabile; restituisce id e requires_capability. |
| Allegati | delete_attachment | Elimina definitivamente un allegato della propria organizzazione, compreso il file archiviato. |
| Database Sync | list_database_syncs | Elenca le registrazioni database, gli schemi collegati, le opzioni e gli host di sync di uno schema salvato. |
| Database Sync | list_entity_states | Esplora le righe di entità unite correnti di uno schema, non i record per singola esecuzione. |
| Database Sync | create_database_sync | Registra uno schema salvato per la sincronizzazione relazionale verso PostgreSQL, MySQL o SQLite. |
| Database Sync | assign_sync_host | Assegna o rimuove l'host che effettua il provisioning di una sincronizzazione database. |
| Database Sync | classify_database_model | Avvia un'analisi a pagamento che propone chiavi di database, tipi SQL, indici e titolarità delle relazioni su uno schema collegato. |
| Database Sync | delete_database_sync | Elimina la registrazione di un database e i relativi delta in coda, interrompendone il feed. |
| Database Sync | get_database_setup_instructions | Restituisce istruzioni non riservate di installazione, di associazione confermata dal browser e di esecuzione per un client ee-database sync. |
| Database Sync | fetch_database_deltas | Legge la finestra ordinata successiva di delta SQL e payload canonici per un database sync. |
| Database Sync | ack_database_deltas | Confermare ogni delta tramite up_to_id dopo l'applicazione riuscita, rilasciandone il lease. |
| Database Sync | sync_records_to_database | Convalida e inserisce l'output di arricchimento memorizzato o fornito nel livello delle entità e nelle sincronizzazioni collegate. |
| ID semantici | list_semantic_concepts | Esplora i concetti dell'organizzazione con alias, conteggi di utilizzo e facet per tipo/modello. |
| ID semantici | get_semantic_concept | Legge 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 semantici | probe_semantic_concept | Anteprima della risoluzione dell'identità senza aggiungere un concetto né incrementarne l'utilizzo. |
| ID semantici | add_semantic_concept | Aggiunge un concetto di identità con utilizzo zero, oppure aggiunge un testo come alias tramite alias_of. |
| ID semantici | update_concept_alias | Rimuove o promuove un alias di concetto usando gli ID alias restituiti da get_semantic_concept. |
| ID semantici | import_semantic_concepts | Risolve 1..1000 testi rispetto a un unico tipo di concetto. |
| ID semantici | merge_semantic_concepts | Unisce un concetto perdente in uno vincente. |
| ID semantici | delete_semantic_concepts | Elimina i concetti selezionati tramite ids, concept_types o unused_only. |
| ID semantici | migrate_semantic_embeddings | Ispeziona o migra lo spazio di embedding dei concetti dell'organizzazione. |
| Supporto prodotto | ask_support | Ponga 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 prodotto | get_support_conversation | Legga 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 prodotto | list_support_conversations | I 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). |
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.
Per impostazione predefinita, ogni job che avvia viene eseguito sul suo modello: risponda a ciascuna delle relative chiamate al modello con `answer_llm_request` e lasci che la piattaforma convalidi ogni risposta rispetto allo schema. `use_platform_models=true` esegue invece il job sulla piattaforma, con il modello migliore secondo il benchmark dell'organizzazione per l'attività.
Progettare uno schema riutilizzabile a partire da esempi revisionati, inclusi identità, relazioni e campi multilingue.
Legge, crea e modifica i documenti di schema di Entity Enricher senza confondere JSON Schema serializzato, dati di esempio e percorsi degli strumenti per le proprietà.
Scegliere tra estrazione, arricchimento basato su conoscenza o una combinazione a due passaggi, preservando la provenienza degli allegati tra le chiamate.
Arricchire un'entità, interpretarne l'esito effettivo e recuperare gli errori parziali dei modelli senza ripetere il lavoro già riuscito.
Arricchire un elenco di entità in modo asincrono e distinguere i risultati ignorati, non riusciti, fusi e ammessi nel database.
Confronta i modelli su arricchimento, generazione di campioni o generazione di schemi, utilizzando il riferimento e l'interpretazione del punteggio corretti.
Trasforma gli schemi di arricchimento in tabelle relazionali nel proprio database e verifica separatamente l'ammissione, la migrazione e la consegna delle repliche.
Riconosce le entità ricorrenti nelle diverse forme superficiali, esamina le corrispondenze incerte e chiarisce come le modifiche al vocabolario influiscono sulle repliche.
Ponga a Rupert, l'assistente di supporto prodotto, qualsiasi domanda su Entity Enricher, prosegua il thread che ha aperto e legga i follow-up del team di supporto.
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 URI | Descrizione |
|---|---|
| enricher://docs | Indice 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. |
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.
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.
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_code | Quando |
|---|---|
| invalid_request | UUID malformato, argomenti mutuamente esclusivi (schema_id + target_schema) o convalida del corpo della richiesta non riuscita. |
| prompt_limit_reached | Quota di prompt giornaliera / settimanale / mensile esaurita (HTTP 402). Il corpo include periodo, limite, utilizzati e necessari. |
| insufficient_credits | L'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_exceeded | Richiesti più modelli di quanti ne consenta il piano (HTTP 402). Riporta il limite e la quantità richiesta. |
| language_limit_exceeded | Richieste più lingue di quante ne consenta il piano (HTTP 402). |
| concurrent_job_limit_reached | Troppi 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_plan | Il 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_reached | La 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_user | ask_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_unavailable | L'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_undecided | Un 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_auto | Un 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_pending | answer_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_pending | answer_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_timeout | Un 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_disabled | analyze_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_timeout | Il job ha superato timeout_seconds. Suggeriamo di ridurre i modelli o di suddividere l'entity. |
| schema_generation_timeout | La generazione dello schema ha superato timeout_seconds. |
| schema_generation_failed | Errore LLM upstream durante la generazione dello schema (HTTP 502). |
| model_output_invalid | Il 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. |
| cancelled | Il job è stato annullato durante l'esecuzione (HTTP 499). |
| not_found | Lo schema o l'ID del record non esiste nella vostra organizzazione. |
| http_error | Gestione generica per gli errori HTTP privi di un corpo di dettaglio strutturato. |
get_stats copre i riepiloghi lato chat; le dashboard complete restano nell'app.