Utilizzare la derivazione dei dati con MCP, Gemini e altri agenti

Questa pagina spiega come connettere la tracciabilità dei dati a strumenti per sviluppatori come Gemini CLI e altri client Model Context Protocol (MCP). La connessione della tracciabilità dei dati a questi strumenti consente il monitoraggio della tracciabilità basato sull'AI e l'analisi della provenienza dei dati direttamente nel tuo ambiente di sviluppo.

Puoi connettere IDE e strumenti per sviluppatori che supportano MCP utilizzando una versione locale di MCP Toolbox for Databases. Puoi quindi utilizzare gli agenti AI nel tuo IDE esistente per eseguire query sui grafici di derivazione dei dati, scoprire la provenienza dei dati upstream e analizzare l'impatto downstream sulle tue risorse.

Per saperne di più su MCP, consulta Introduzione al Model Context Protocol.

Questa guida illustra la procedura di connessione per i seguenti strumenti:

• Gemini CLI
• Gemini Code Assist
• Claude Code
• Claude desktop
• Codex
• Cline (estensione VS Code)
• Cursor
• Visual Studio Code (Copilot)
• Windsurf (in precedenza Codeium)

Quali strumenti MCP fornisce la derivazione dei dati?

L'integrazione della tracciabilità dei dati consente agli agenti AI di eseguire query e analizzare la tracciabilità dei dati, che rappresenta il flusso di dati tra le risorse di origine (upstream) e di destinazione (downstream). Supporta sia la tracciabilità a livello di entità (monitoraggio del flusso di dati tra intere risorse come tabelle e file) sia la tracciabilità a livello di colonna (monitoraggio del flusso di dati tra campi o colonne specifici all'interno delle risorse).

La derivazione dei dati fornisce lo strumento datalineage-search-lineage, che recupera una risposta di streaming dei link di derivazione collegati alle risorse richieste.

Per saperne di più sull'origine della tracciabilità dei dati e sugli strumenti disponibili, consulta la documentazione relativa all'origine della tracciabilità dei dati.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per connetterti alla tracciabilità dei dati utilizzando MCP Toolbox, chiedi all'amministratore di concederti i seguenti ruoli IAM nel tuo progetto:

• Per abilitare le API: Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin)
• Per utilizzare le competenze di derivazione dei dati: Visualizzatore derivazione dei dati (roles/datalineage.viewer)

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questi ruoli predefiniti contengono le autorizzazioni necessarie per connetterti alla tracciabilità dei dati utilizzando MCP Toolbox. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per connetterti alla tracciabilità dei dati utilizzando MCP Toolbox sono necessarie le seguenti autorizzazioni:

• Per abilitare le API: serviceusage.services.enable
• Per utilizzare le skill di tracciabilità dei dati:
  • datalineage.lineage.searchLinks
  • datalineage.processes.get
  • datalineage.runs.get

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Abilita le API richieste

1. Nella Google Cloud console, vai alla pagina di selezione del progetto.

   Vai al selettore di progetti

2. Seleziona o crea un Google Cloud progetto.

   Ruoli richiesti per selezionare o creare un progetto

   • Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto su cui ti è stato concesso un ruolo.
   • Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l' resourcemanager.projects.create autorizzazione. Scopri come concedere i ruoli.
   Nota: se non prevedi di conservare le risorse che crei in questa procedura, crea un progetto anziché selezionarne uno esistente. Al termine di questi passaggi, puoi eliminare il progetto, rimuovendo tutte le risorse associate.

3. Verifica che la fatturazione sia abilitata per il tuo Google Cloud progetto.

4. Abilita l'API Data Lineage.

   Ruoli richiesti per abilitare le API

   Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

   Abilitare l'API

5. Se utilizzi una shell locale, crea le credenziali di autenticazione locali per il tuo account utente:

   gcloud auth application-default login

   Non è necessario eseguire questa operazione se utilizzi Cloud Shell.

   Se viene restituito un errore di autenticazione e utilizzi un provider di identità (IdP) esterno, verifica di aver acceduto a gcloud CLI con la tua identità federata.

Installa MCP Toolbox

Non è necessario installare MCP Toolbox se prevedi di utilizzare solo Gemini Code Assist, in quanto include le funzionalità del server richieste. Per altri IDE e strumenti, segui i passaggi descritti in questa sezione per installare MCP Toolbox.

1. Scarica l'ultima versione di MCP Toolbox come file binario. Seleziona la release binaria di MCP Toolbox corrispondente alla tua architettura (sistema operativo) e architettura della CPU. Devi utilizzare MCP Toolbox v0.31.0 o versioni successive.

   Linux/amd64

   curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/VERSION/linux/amd64/toolbox

   Sostituisci VERSION con la versione di MCP Toolbox, ad esempio v0.31.0.

   macOS (Darwin)/arm64

   curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/VERSION/darwin/arm64/toolbox

   Sostituisci VERSION con la versione di MCP Toolbox, ad esempio v0.31.0.

   macOS (Darwin)/amd64

   curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/VERSION/darwin/amd64/toolbox

   Sostituisci VERSION con la versione di MCP Toolbox, ad esempio v0.31.0.

   Windows/amd64

   curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/VERSION/windows/amd64/toolbox

   Sostituisci VERSION con la versione di MCP Toolbox, ad esempio v0.31.0.

2. Rendi eseguibile il file binario:

   chmod +x toolbox
   

3. Verifica l'installazione:

   ./toolbox --version
   

   Un'installazione riuscita restituisce il numero di versione, ad esempio 0.15.0.

Configura client e connessioni per la derivazione dei dati

Questa sezione spiega come connettere la tracciabilità dei dati ai tuoi strumenti.

Per connettere gli IDE e gli strumenti compatibili con MCP alla tracciabilità dei dati, devi prima installare MCP Toolbox e creare un file di configurazione personalizzato per l'origine e gli strumenti di tracciabilità.

**Nota** :non è necessario installare MCP Toolbox se prevedi di utilizzare solo Gemini Code Assist.

1. Nella directory root del progetto o nella directory di configurazione, crea un file YAML denominato lineage-config.yaml con la seguente configurazione:

   kind: source
   name: lineage-source
   type: datalineage
   project: ${DATALINEAGE_PROJECT}
   ---
   kind: tool
   name: search_lineage
   type: datalineage-search-lineage
   source: lineage-source
   description: Retrieves a streaming response of lineage links connected to requested assets.
   

2. Imposta la variabile di ambiente per il tuo Google Cloud progetto:

   export DATALINEAGE_PROJECT=PROJECT_ID
   

   Sostituisci PROJECT_ID con l' Google Cloud ID progetto.

3. Configura il client specifico utilizzando il flag --config anziché una configurazione predefinita, come mostrato nelle sezioni seguenti.

Gemini CLI

Puoi utilizzare la derivazione dei dati in Gemini CLI configurandola come server MCP locale utilizzando MCP Toolbox e il file lineage-config.yaml personalizzato.

1. Nella directory di lavoro del progetto, crea una cartella denominata .gemini (o apri la directory globale ~/.gemini directory).
2. All'interno di questa directory, crea o apri il file settings.json.

3. Aggiungi la seguente configurazione:

   {
     "mcpServers": {
       "dataLineage": {
         "command": "./PATH/TO/toolbox",
         "args": ["--config","/PATH/TO/lineage-config.yaml","--stdio"],
         "env": {
           "DATALINEAGE_PROJECT": "PROJECT_ID"
         }
       }
     }
   }
   

   Sostituisci PROJECT_ID con l' Google Cloud ID progetto.

4. Salva la configurazione.

5. Avvia Gemini CLI in modalità interattiva:

   gemini
   

   In Gemini CLI, utilizza il /mcp comando per verificare che il dataLineage server è connesso.

Gemini Code Assist

Gemini Code Assist include le funzionalità del server MCP richieste, quindi non è necessario installare MCP Toolbox separatamente.

1. In VS Code, installa l' estensione Gemini Code Assist.
2. Attiva la modalità agente nella chat di Gemini Code Assist.
3. Nella directory di lavoro, crea una cartella denominata .gemini. Al suo interno, crea un file settings.json.

4. Aggiungi la seguente configurazione:

   {
     "mcpServers": {
       "dataLineage": {
         "command": "./PATH/TO/toolbox",
         "args": ["--config","/PATH/TO/lineage-config.yaml","--stdio"],
         "env": {
           "DATALINEAGE_PROJECT": "PROJECT_ID"
         }
       }
     }
   }
   

   Sostituisci PROJECT_ID con l' Google Cloud ID progetto.

5. Salva la configurazione.

Claude Code

Sebbene il plug-in ufficiale fornisca strumenti per Knowledge Catalog, puoi utilizzare la tracciabilità dei dati in Claude Code configurando un server MCP Toolbox locale con il file di configurazione personalizzato.

1. Imposta la variabile di ambiente per connetterti al progetto di tracciabilità dei dati:

   export DATALINEAGE_PROJECT=PROJECT_ID
   

   Sostituisci PROJECT_ID con l' Google Cloud ID progetto.

2. Configura Claude Code per utilizzare il server MCP Toolbox:

   claude mcp add datalineage -- /PATH/TO/toolbox --config=/PATH/TO/lineage-config.yaml --stdio
   

3. Avvia l'agente:

   claude
   

Codex

Per utilizzare la tracciabilità dei dati in Codex, configura una connessione al server MCP nella configurazione di Codex per eseguire MCP Toolbox con il file lineage-config.yaml personalizzato:

1. Imposta la variabile di ambiente per connetterti al progetto di tracciabilità dei dati:

   export DATALINEAGE_PROJECT="PROJECT_ID"
   

   Sostituisci PROJECT_ID con l' Google Cloud ID progetto.

2. Nella configurazione MCP di Codex, aggiungi il server utilizzando MCP Toolbox:

   {
     "mcpServers": {
       "dataLineage": {
         "command": "./PATH/TO/toolbox",
         "args": ["--config","/PATH/TO/lineage-config.yaml","--stdio"],
         "env": {
           "DATALINEAGE_PROJECT": "PROJECT_ID"
         }
       }
     }
   }
   

   Sostituisci PROJECT_ID con l' Google Cloud ID progetto.

Claude desktop

1. Apri Claude Desktop e vai a Impostazioni.
2. Per aprire il file di configurazione, nella scheda Sviluppatore fai clic su Modifica configurazione.

3. Aggiungi la configurazione:

   {
     "mcpServers": {
       "dataLineage": {
         "command": "./PATH/TO/toolbox",
         "args": ["--config","/PATH/TO/lineage-config.yaml","--stdio"],
         "env": {
           "DATALINEAGE_PROJECT": "PROJECT_ID"
         }
       }
     }
   }
   

   Sostituisci PROJECT_ID con l' Google Cloud ID progetto.

4. Salva la configurazione.

5. Riavvia Claude desktop. Nella nuova schermata della chat viene visualizzata un'icona MCP che rappresenta il nuovo server MCP.

Cline

1. In VS Code, apri l'estensione Cline e fai clic sull'icona Server MCP.
2. Per aprire il file di configurazione, tocca Configura server MCP.

3. Aggiungi la seguente configurazione:

   {
     "mcpServers": {
       "dataLineage": {
         "command": "./PATH/TO/toolbox",
         "args": ["--config","/PATH/TO/lineage-config.yaml","--stdio"],
         "env": {
           "DATALINEAGE_PROJECT": "PROJECT_ID"
         }
       }
     }
   }
   

   Sostituisci PROJECT_ID con l' Google Cloud ID progetto.

4. Salva la configurazione. Dopo la connessione al server, viene visualizzato uno stato attivo verde.

Cursor

1. Crea la directory .cursor nella directory root del progetto, se non esiste.
2. Crea il file .cursor/mcp.json, se non esiste, e aprilo.

3. Aggiungi la seguente configurazione:

   {
     "mcpServers": {
       "dataLineage": {
         "command": "./PATH/TO/toolbox",
         "args": ["--config","/PATH/TO/lineage-config.yaml","--stdio"],
         "env": {
           "DATALINEAGE_PROJECT": "PROJECT_ID"
         }
       }
     }
   }
   

   Sostituisci PROJECT_ID con l' Google Cloud ID progetto.

4. Salva la configurazione.

5. Apri Cursor e vai a Impostazioni > Impostazioni cursore > MCP. Quando il server si connette, viene visualizzato uno stato attivo verde.

VS Code (Copilot)

1. Apri VS Code e crea la directory .vscode nella directory root del progetto, se non esiste.
2. Crea il file .vscode/mcp.json, se non esiste, e aprilo.

3. Aggiungi la seguente configurazione:

   {
     "servers": {
       "dataLineage": {
         "command": "./PATH/TO/toolbox",
         "args": ["--config","/PATH/TO/lineage-config.yaml","--stdio"],
         "env": {
           "DATALINEAGE_PROJECT": "PROJECT_ID"
         }
       }
     }
   }
   

   Sostituisci PROJECT_ID con l' Google Cloud ID progetto.

4. Salva la configurazione.

Windsurf

1. Apri Windsurf e vai all'assistente Cascade.
2. Per aprire il file di configurazione, fai clic sull'icona MCP e poi su Configura.

3. Aggiungi la seguente configurazione:

   {
     "mcpServers": {
       "dataLineage": {
         "command": "./PATH/TO/toolbox",
         "args": ["--config","/PATH/TO/lineage-config.yaml","--stdio"],
         "env": {
           "DATALINEAGE_PROJECT": "PROJECT_ID"
         }
       }
     }
   }
   

   Sostituisci PROJECT_ID con l' Google Cloud ID progetto.

4. Salva la configurazione.

Utilizza le competenze

L'assistente AI è ora connesso alla derivazione dei dati. Prova a chiedere all'assistente AI di tracciare la tracciabilità dei dati upstream e downstream tra le tue risorse.

Ad esempio, puoi chiedere all'assistente AI di:

• Trace l'origine dei dati di una tabella BigQuery (derivazione upstream).
• Scoprire quali tabelle o report downstream dipendono da una risorsa dati specifica (derivazione downstream).
• Esaminare la derivazione a livello di colonna tra campi specifici nelle risorse.

(Facoltativo) Aggiungi istruzioni di sistema

Le istruzioni di sistema sono un modo per fornire linee guida specifiche all'LLM, aiutandolo a comprendere il contesto e a rispondere in modo più accurato. Configura le istruzioni di sistema in base al prompt di sistema consigliato per la tracciabilità dei dati.

Ad esempio, puoi aggiungere istruzioni per guidare l'LLM su come utilizzare le skill di tracciabilità dei dati:

• Quando ti viene chiesto di tracciare il flusso di dati upstream o downstream tra risorse o colonne, utilizza la competenza search_lineage o lo strumento datalineage-search-lineage.

Nota: ti consigliamo di eseguire questo passaggio facoltativo per un'esperienza migliore ed evitare lavoro aggiuntivo, ad esempio la progettazione di un agente personalizzato.

Per saperne di più su come configurare le istruzioni, consulta Utilizzare le istruzioni per ottenere modifiche AI che seguono lo stile di codifica.

Passaggi successivi

• Esamina la differenza tra server MCP locali e remoti.
• Scopri come utilizzare il server MCP Toolbox locale per Knowledge Catalog.
• Leggi le informazioni di riferimento sugli strumenti MCP di derivazione dei dati.
• Scopri di più sulla tracciabilità dei dati.
• Cerca risorse in Knowledge Catalog.