Per configurare NVIDIA Auto Ontology MCP con Cursor o Claude Desktop, prepara prima un deployment di Auto Ontology con un database attivo e il livello semantico compilato; solo dopo avvia il server MCP e collega il client a http://localhost:3003/mcp.
MCP, il Model Context Protocol, consente al client di comunicare con il server. Il server MCP di NVIDIA è un client HTTP dell’API pubblica di Auto Ontology: non è un connettore autonomo al database e non conserva le credenziali del database. La documentazione MCP di NVIDIA descrive il flusso e i controlli necessari per le query.
Cosa preparare prima di collegare il client
Per il quickstart locale, NVIDIA indica Docker con Compose v2, uv, una chiave API NVIDIA e il database di esempio Wide World Importers. Nel file .env vanno impostati i valori per DEFAULT_MODELS_API_KEY, AUTH_SECRET, APP_URL, POSTGRES_PASSWORD, CONNECTION_STRINGS, AUTO_ONTOLOGY_ADMIN_PASSWORD e PGADMIN_PASSWORD. Il file include anche chiavi per singoli modelli: puoi sostituirle oppure eliminarle per usare DEFAULT_MODELS_API_KEY.
Compose pubblica sull’host PostgreSQL, pgAdmin e l’app web. Sostituisci quindi le password predefinite prima di avviare i servizi. NVIDIA descrive requisiti e variabili nel README ufficiale di Auto Ontology.
Avvia Auto Ontology e compila il livello semantico
Segui la sequenza del quickstart: il server MCP viene dopo la preparazione del database e dell’applicazione.
- Configura l’ambiente. Copia
.env.examplein.enve imposta le chiavi e le password richieste, comprese quelle dell’amministratore e di pgAdmin. - Avvia PostgreSQL e carica i dati di esempio. NVIDIA indica Wide World Importers e lo script di seed
auto-ontology-evalper popolare il database. - Avvia gli altri servizi Compose. In questo modo parte anche l’app web, che nell’architettura locale usa la porta
3000. - Accedi all’app web con l’account amministratore. L’accesso serve per attivare la compilazione semantica dalle impostazioni.
- Avvia la compilazione semantica. In Settings → Semantic Compilation, attendi il messaggio “Semantic compilation is ready”. Per rispondere alle domande servono sia questo livello compilato sia una connessione al database ancora attiva.
- Avvia il pacchetto MCP puntandolo all’app web. NVIDIA indica il pacchetto nella sottocartella
mcpdel repository, eseguito conuvx, e la variabileAUTO_ONTOLOGY_API_URL=http://localhost:3000. Il server MCP espone l’endpoint sulla porta3003; l’indirizzo completo da usare nel client termina con/mcp.
Configura Cursor o Claude Desktop
I due client usano configurazioni diverse, ma puntano allo stesso endpoint. Cursor registra direttamente l’URL HTTP; l’esempio NVIDIA per Claude Desktop avvia npx e passa l’endpoint a mcp-remote.
| Client | File e impostazione | Endpoint o comando |
| Cursor | ~/.cursor/mcp.json, sotto mcpServers.auto-ontology.url | http://localhost:3003/mcp |
| Claude Desktop | claude_desktop_config.json, con command impostato su npx | args: mcp-remote e http://localhost:3003/mcp |
Dopo aver salvato la configurazione, riavvia il client. Quando compare la richiesta di accesso, autentícati tramite Auto Ontology: le credenziali non vanno inserite nella configurazione MCP. Ogni chiamata usa i permessi dell’utente che ha effettuato l’accesso.
Diagnostica accesso e query
Se il client non avvia l’accesso, controlla che il deployment risponda con HTTP 200 all’indirizzo /.well-known/oauth-authorization-server. Alcune immagini già compilate in precedenza possono non includere la route richiesta dal flusso di autenticazione. Se compare un errore sull’indirizzo della risorsa protetta, verifica che client e server usino lo stesso nome host: localhost e 127.0.0.1 non sono intercambiabili in quell’URL. In tal caso, imposta AUTO_ONTOLOGY_MCP_PUBLIC_URL sullo stesso indirizzo usato dal client.
Quando una query non restituisce una risposta utile, controlla nell’ordine la disponibilità del deployment, la copertura dei termini e poi il risultato SQL.
Inizia con check_readiness: segnala gli impedimenti, fra cui la mancata compilazione semantica o l’assenza di una connessione database attiva. Un catalogo di database ancora visibile non basta a dimostrare che la connessione funzioni: i metadati possono restare anche dopo che il collegamento al database è venuto meno.
Se la readiness è a posto ma il vocabolario della domanda non viene riconosciuto, usa search_terms per cercare i termini disponibili; poi check_answerable per verificare se la domanda è coperta e ask_question per eseguirla. Quest’ultimo restituisce risposta, SQL e righe, fino a un massimo di 100: i campi row_count e truncated indicano il numero di righe e se il risultato è stato troncato. Il server espone nove strumenti in sola lettura; le chiamate non modificano l’ontologia o il database.
Un errore 403 quando un utente con ruolo viewer prova a leggere le impostazioni delle connessioni può dipendere dal fatto che quella consultazione è riservata agli amministratori, non necessariamente da un deployment non funzionante.
Mantieni privati backend e servizio di ingestione
NVIDIA raccomanda di tenere sulla rete privata le porte 3001 e 3002: il backend si fida dell’identità inoltrata dal frontend e le operazioni del servizio di ingestione non hanno un’autenticazione indipendente. Le porte corrispondono ai servizi backend e di ingestione/compilazione semantica, non all’endpoint MCP destinato al client.