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.

  1. Configura l’ambiente. Copia .env.example in .env e imposta le chiavi e le password richieste, comprese quelle dell’amministratore e di pgAdmin.
  2. Avvia PostgreSQL e carica i dati di esempio. NVIDIA indica Wide World Importers e lo script di seed auto-ontology-eval per popolare il database.
  3. Avvia gli altri servizi Compose. In questo modo parte anche l’app web, che nell’architettura locale usa la porta 3000.
  4. Accedi all’app web con l’account amministratore. L’accesso serve per attivare la compilazione semantica dalle impostazioni.
  5. 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.
  6. Avvia il pacchetto MCP puntandolo all’app web. NVIDIA indica il pacchetto nella sottocartella mcp del repository, eseguito con uvx, e la variabile AUTO_ONTOLOGY_API_URL=http://localhost:3000. Il server MCP espone l’endpoint sulla porta 3003; 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.

ClientFile e impostazioneEndpoint o comando
Cursor~/.cursor/mcp.json, sotto mcpServers.auto-ontology.urlhttp://localhost:3003/mcp
Claude Desktopclaude_desktop_config.json, con command impostato su npxargs: 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.