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

Questa pagina spiega come connettere la lineage dei dati a strumenti per sviluppatori come Gemini CLI e altri client Model Context Protocol (MCP). Il collegamento della lineage dei dati a questi strumenti consente il monitoraggio della lineage 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 un MCP Toolbox for Databases locale. Puoi quindi utilizzare gli agenti AI nel tuo IDE esistente per eseguire query sui grafici della derivazione dei dati, scoprire la provenienza dei dati upstream e analizzare l'impatto downstream sugli asset.

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

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

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 gli asset di origine (upstream) e di destinazione (downstream). Supporta sia la tracciabilità a livello di entità (monitoraggio del flusso di dati tra interi asset come tabelle e file) sia la tracciabilità a livello di colonna (monitoraggio del flusso di dati tra campi o colonne specifici all'interno degli asset).

La tracciabilità dei dati fornisce lo strumento datalineage-search-lineage, che recupera una risposta in streaming dei link di tracciabilità collegati agli asset richiesti.

Per saperne di più sull'origine della tracciabilità dei dati e sugli strumenti disponibili, consulta la documentazione sull'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 saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

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

Autorizzazioni obbligatorie

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

  • Per abilitare le API: serviceusage.services.enable
  • Per utilizzare le competenze 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 console Google Cloud , 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 per il quale ti è stato concesso un ruolo.
    • Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l'autorizzazione resourcemanager.projects.create. Scopri come concedere i ruoli.

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

  4. Abilita l'API Data Lineage, se non è già abilitata.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente disponi già di questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore utilizzo dei servizi (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 versione binaria di MCP Toolbox corrispondente al tuo sistema operativo e alla tua 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.

Configurare client e connessioni per la derivazione dei dati

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

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

  1. Nella directory radice del progetto o 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'ID progetto Google Cloud .

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

Gemini CLI

Puoi utilizzare la tracciabilità dei dati nella Gemini CLI configurandola come server MCP locale utilizzando MCP Toolbox e il tuo file lineage-config.yaml personalizzato.

  1. Nella directory di lavoro del progetto, crea una cartella denominata .gemini (o apri la directory globale ~/.gemini).
  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'ID progetto Google Cloud .

  4. Salva la configurazione.

  5. Avvia Gemini CLI in modalità interattiva:

    gemini

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

Gemini Code Assist

Gemini Code Assist raggruppa 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'ID progetto Google Cloud .

  5. Salva la configurazione.

Claude Code

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

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

    export DATALINEAGE_PROJECT=PROJECT_ID

    Sostituisci PROJECT_ID con l'ID progetto Google Cloud .

  2. Configura Claude Code in modo che utilizzi 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 derivazione dei dati in Codex, configura una connessione al server MCP nella configurazione di Codex per eseguire MCP Toolbox con il tuo file lineage-config.yaml personalizzato:

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

    export DATALINEAGE_PROJECT="PROJECT_ID"

    Sostituisci PROJECT_ID con l'ID progetto Google Cloud .

  2. Nella configurazione di Codex MCP, 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'ID progetto Google Cloud .

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'ID progetto Google Cloud .

  4. Salva la configurazione.

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

Cline

  1. In VS Code, apri l'estensione Cline e poi 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'ID progetto Google Cloud .

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

Cursore

  1. Crea la directory .cursor nella 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'ID progetto Google Cloud .

  4. Salva la configurazione.

  5. Apri Cursore 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 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'ID progetto Google Cloud .

  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, quindi 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'ID progetto Google Cloud .

  4. Salva la configurazione.

Utilizzare le competenze

Il tuo assistente AI è ora connesso alla tracciabilità dei dati. Prova a chiedere al tuo assistente AI di tracciare la tracciabilità dei dati upstream e downstream tra i tuoi asset.

Ad esempio, puoi chiedere all'assistente AI di:

  • Trace l'origine dei dati di una tabella BigQuery (tracciabilità upstream).
  • Scopri quali tabelle o report downstream dipendono da uno specifico asset di dati (tracciabilità downstream).
  • Esamina la derivazione a livello di colonna tra campi specifici negli asset.

(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 lineage dei dati.

Ad esempio, puoi aggiungere istruzioni per guidare l'LLM su come utilizzare le competenze di data lineage:

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

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

Passaggi successivi