Usar linhagem de dados com MCP, Gemini e outros agentes

Nesta página, explicamos como conectar a linhagem de dados a ferramentas de desenvolvedor, como a CLI do Gemini e outros clientes do Protocolo de Contexto de Modelo (MCP). Ao conectar a linhagem de dados a essas ferramentas, é possível fazer o rastreamento da linhagem e a análise de procedência de dados orientados por IA diretamente no ambiente de desenvolvimento.

Você pode conectar IDEs e ferramentas de desenvolvedor compatíveis com o MCP usando uma MCP Toolbox for Databases local. Em seguida, use agentes de IA no seu IDE para consultar gráficos de linhagem de dados, descobrir a procedência de dados upstream e analisar o impacto downstream nos seus recursos.

Para mais informações sobre o MCP, consulte Introdução ao Protocolo de Contexto de Modelo.

Este guia demonstra o processo de conexão das seguintes ferramentas:

Quais ferramentas do MCP a linhagem de dados oferece?

A integração da linhagem de dados permite que os agentes de IA consultem e analisem a linhagem de dados, representando o fluxo de dados entre recursos de origem (upstream) e de destino (downstream). Ela oferece suporte à linhagem no nível da entidade (rastreamento do fluxo de dados entre recursos inteiros, como tabelas e arquivos) e no nível da coluna (rastreamento do fluxo de dados entre campos ou colunas específicos nos recursos).

A linhagem de dados fornece a ferramenta datalineage-search-lineage, que recupera uma resposta de streaming de links de linhagem conectados aos recursos solicitados.

Para mais informações sobre a origem da linhagem de dados e as ferramentas disponíveis, consulte a documentação da origem da linhagem de dados.

Funções exigidas

Para receber as permissões necessárias para se conectar à linhagem de dados usando a MCP Toolbox, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para se conectar à linhagem de dados usando a MCP Toolbox. Para acessar as permissões exatas que são necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para se conectar à linhagem de dados usando a MCP Toolbox:

  • Para ativar APIs: serviceusage.services.enable
  • Para usar habilidades de linhagem de dados:
    • datalineage.lineage.searchLinks
    • datalineage.processes.get
    • datalineage.runs.get

Essas permissões também podem ser concedidas com papéis personalizados ou outros papéis predefinidos.

Ative as APIs necessárias

  1. No Google Cloud console do, acesse a página Seletor de Projetos.

    Acessar o seletor de projetos

  2. Selecione ou crie um Google Cloud projeto do.

    Funções necessárias para selecionar ou criar um projeto

    • Selecionar um projeto: a seleção de um projeto não exige um papel específico do IAM. Você pode selecionar qualquer projeto em que tenha recebido um papel.
    • Criar um projeto: para criar um projeto, é necessário ter o papel de Criador de projetos (roles/resourcemanager.projectCreator), que contém a resourcemanager.projects.create permissão. Saiba como conceder papéis.

  3. Verifique se o faturamento está ativado para o Google Cloud projeto.

  4. Ative a API Data Lineage.

    Funções necessárias para ativar APIs

    Para ativar as APIs, é necessário ter a permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de Proprietário (roles/owner). Caso contrário, você pode receber essa permissão pelo papel de Administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

    Ativar a API

  5. Se você estiver usando um shell local, crie credenciais de autenticação local para sua conta de usuário: 

    gcloud auth application-default login

    Não é necessário fazer isso se você estiver usando o Cloud Shell.

    Se um erro de autenticação for retornado e você estiver usando um provedor de identidade (IdP) externo, confirme se você fez login na CLI gcloud com sua identidade federada.

Instalar o MCP Toolbox

Não é necessário instalar a MCP Toolbox se você pretende usar apenas o Gemini Code Assist, porque ele agrupa os recursos de servidor necessários. Para outros IDEs e ferramentas, siga as etapas desta seção para instalar a MCP Toolbox.

  1. Faça o download da versão mais recente da MCP Toolbox como um binário. Selecione a versão binária da MCP Toolbox que corresponde ao seu SO e à arquitetura de CPU. Use a MCP Toolbox v0.31.0 ou mais recente.

    Linux/amd64

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

    Substitua VERSION pela versão da MCP Toolbox. Por exemplo, v0.31.0.

    macOS (Darwin)/arm64

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

    Substitua VERSION pela versão da MCP Toolbox. Por exemplo, v0.31.0.

    macOS (Darwin)/amd64

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

    Substitua VERSION pela versão da MCP Toolbox. Por exemplo, v0.31.0.

    Windows/amd64

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

    Substitua VERSION pela versão da MCP Toolbox. Por exemplo, v0.31.0.

  2. Torne o binário executável:

    chmod +x toolbox

  3. Verifique a instalação:

    ./toolbox --version

    Uma instalação bem-sucedida retorna o número da versão, por exemplo, 0.15.0.

Configurar clientes e conexões para linhagem de dados

Esta seção explica como conectar a linhagem de dados às suas ferramentas.

Para conectar seus IDEs e ferramentas compatíveis com o MCP à linhagem de dados, você deve primeiro instalar a MCP Toolbox e criar um arquivo de configuração personalizado para sua origem e ferramentas de linhagem.

  1. No diretório raiz ou de configuração do projeto, crie um arquivo YAML chamado lineage-config.yaml com a seguinte configuração:

    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. Defina a variável de ambiente para o projeto do Google Cloud :

    export DATALINEAGE_PROJECT=PROJECT_ID

    Substitua PROJECT_ID pelo Google Cloud ID do projeto.

  3. Configure seu cliente específico usando a flag --config em vez de uma configuração pré-criada, conforme mostrado nas seções a seguir.

CLI do Gemini

Você pode usar a linhagem de dados na CLI do Gemini configurando-a como um servidor MCP local usando a MCP Toolbox e o arquivo lineage-config.yaml personalizado.

  1. No diretório de trabalho do projeto, crie uma pasta chamada .gemini ou abra o diretório global ~/.gemini.
  2. Nesse diretório, crie ou abra o arquivo settings.json.

  3. Adicione a seguinte configuração:

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

    Substitua PROJECT_ID pelo Google Cloud ID do projeto.

  4. Salve a configuração.

  5. Inicie a CLI do Gemini no modo interativo:

    gemini

    Na CLI do Gemini, use o /mcp comando para verificar se o dataLineage servidor está conectado.

Gemini Code Assist

O Gemini Code Assist agrupa os recursos necessários do servidor MCP. Portanto, não é necessário instalar a MCP Toolbox separadamente.

  1. No VS Code, instale a extensão do Gemini Code Assist.
  2. Ative o Modo Agente no chat do Gemini Code Assist.
  3. No diretório de trabalho, crie uma pasta chamada .gemini. Nela, crie um arquivo settings.json.

  4. Adicione a seguinte configuração:

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

    Substitua PROJECT_ID pelo Google Cloud ID do projeto.

  5. Salve a configuração.

Claude Code

Embora o plug-in oficial forneça ferramentas para o Knowledge Catalog, você pode usar a linhagem de dados no Claude Code configurando um servidor MCP Toolbox local com seu arquivo de configuração personalizado.

  1. Defina a variável de ambiente para se conectar ao projeto de linhagem de dados:

    export DATALINEAGE_PROJECT=PROJECT_ID

    Substitua PROJECT_ID pelo Google Cloud ID do projeto.

  2. Configure o Claude Code para usar o servidor MCP Toolbox:

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

  3. Inicie o agente:

    claude

Codex

Para usar a linhagem de dados no Codex, configure uma conexão de servidor MCP na configuração do Codex para executar a MCP Toolbox com o arquivo lineage-config.yaml personalizado:

  1. Defina a variável de ambiente para se conectar ao projeto de linhagem de dados:

    export DATALINEAGE_PROJECT="PROJECT_ID"

    Substitua PROJECT_ID pelo Google Cloud ID do projeto.

  2. Na configuração do Codex MCP, adicione o servidor usando a MCP Toolbox:

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

    Substitua PROJECT_ID pelo Google Cloud ID do projeto.

Claude Desktop

  1. Abra o Claude Desktop e navegue até Configurações.
  2. Para abrir o arquivo de configuração, na guia Desenvolvedor , clique em Editar configuração.

  3. Adicione a configuração:

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

    Substitua PROJECT_ID pelo Google Cloud ID do projeto.

  4. Salve a configuração.

  5. Reinicie o Claude Desktop. A nova tela de chat mostra um ícone do MCP que representa o novo servidor MCP.

Cline

  1. No VS Code, abra a extensão Cline e clique no ícone Servidores MCP.
  2. Para abrir o arquivo de configuração, toque em Configurar servidores MCP.

  3. Adicione a seguinte configuração:

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

    Substitua PROJECT_ID pelo Google Cloud ID do projeto.

  4. Salve a configuração. Um status ativo verde aparece depois que o servidor é conectado.

Cursor

  1. Crie o diretório .cursor na raiz do projeto, se ele não existir.
  2. Crie o arquivo .cursor/mcp.json se ele não existir e abra-o.

  3. Adicione a seguinte configuração:

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

    Substitua PROJECT_ID pelo Google Cloud ID do projeto.

  4. Salve a configuração.

  5. Abra o Cursor e navegue até Configurações > Configurações do cursor > MCP. Um status ativo verde aparece quando o servidor se conecta.

VS Code (Copilot)

  1. Abra o VS Code e crie o diretório .vscode na raiz do projeto, se ele não existir.
  2. Crie o arquivo .vscode/mcp.json se ele não existir e abra-o.

  3. Adicione a seguinte configuração:

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

    Substitua PROJECT_ID pelo Google Cloud ID do projeto.

  4. Salve a configuração.

Windsurf

  1. Abra o Windsurf e navegue até o assistente Cascade.
  2. Para abrir o arquivo de configuração, clique no ícone do MCP e em Configurar.

  3. Adicione a seguinte configuração:

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

    Substitua PROJECT_ID pelo Google Cloud ID do projeto.

  4. Salve a configuração.

Usar as habilidades

O assistente de IA agora está conectado à linhagem de dados. Peça ao assistente de IA para rastrear a linhagem de dados upstream e downstream entre seus recursos.

Por exemplo, você pode pedir ao assistente de IA para:

  • Rastrear a origem dos dados de uma tabela do BigQuery (linhagem upstream).
  • Descobrir quais tabelas ou relatórios downstream dependem de um recurso de dados específico (linhagem downstream).
  • Inspecionar a linhagem no nível da coluna entre campos específicos em recursos.

Opcional: adicionar instruções do sistema

As instruções do sistema são uma maneira de fornecer diretrizes específicas ao LLM, ajudando-o a entender o contexto e responder com mais precisão. Configure as instruções do sistema com base no comando do sistema recomendado da linhagem de dados.

Por exemplo, você pode adicionar instruções para orientar o LLM sobre como usar as habilidades de linhagem de dados:

  • Quando solicitado a rastrear o fluxo de dados upstream ou downstream entre recursos ou colunas, use a habilidade search_lineage ou a ferramenta datalineage-search-lineage.

Para mais informações sobre como configurar instruções, consulte Usar instruções para receber edições de IA que seguem seu estilo de programação.

A seguir