Usar linhagem de dados com MCP, Gemini e outros agentes

Esta página explica como conectar a linhagem de dados a ferramentas para desenvolvedores, 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 e a análise de procedência de dados com tecnologia de IA diretamente no ambiente de desenvolvimento.

Você pode conectar IDEs e ferramentas de desenvolvedor que oferecem suporte ao MCP usando uma MCP Toolbox for Databases local. Em seguida, use agentes de IA no seu ambiente de desenvolvimento integrado (IDE) atual para consultar gráficos de linhagem de dados, descobrir a origem dos 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 para as seguintes ferramentas:

Quais ferramentas do MCP a linhagem de dados oferece?

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

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 caixa de ferramentas do MCP, 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 caixa de ferramentas do MCP. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para se conectar à linhagem de dados usando a caixa de ferramentas do MCP:

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

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

Ative as APIs necessárias

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

    Acessar o seletor de projetos

  2. Selecione ou crie um projeto do Google Cloud .

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

    • Selecionar um projeto: não é necessário um papel específico do IAM para selecionar um projeto. Você pode escolher 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 permissão resourcemanager.projects.create. Saiba como conceder papéis.

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

  4. Ative a API Data Lineage, se ela ainda não estiver ativada.

    Funções necessárias para ativar APIs

    Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão com o papel de Proprietário (roles/owner). Caso contrário, é possível receber essa permissão com o papel de Administrador do Service Usage (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, já que ele agrupa os recursos necessários do servidor. Para outras ferramentas e IDEs, 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 o lançamento binário da caixa de ferramentas do MCP que corresponde à sua arquitetura de CPU e SO. Use a MCP Toolbox v0.31.0 ou uma versão mais recente.

    Linux/amd64

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

    Substitua VERSION pela versão do 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 do 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 do 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 do 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 ambientes de desenvolvimento integrado e ferramentas compatíveis com MCP à linhagem de dados, primeiro instale o MCP Toolbox e crie um arquivo de configuração personalizado para sua origem e ferramentas de linhagem.

  1. Na raiz do projeto ou no diretório de configuração, 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 Google Cloud :

    export DATALINEAGE_PROJECT=PROJECT_ID

    Substitua PROJECT_ID pelo ID do projeto Google Cloud .

  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

É possível usar a linhagem de dados na CLI do Gemini configurando-a como um servidor MCP local usando a MCP Toolbox e seu 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 ID do projeto Google Cloud .

  4. Salve a configuração.

  5. Inicie a CLI do Gemini no modo interativo:

    gemini

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

Gemini Code Assist

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

  1. No VS Code, instale a extensão 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. Nele, 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 ID do projeto Google Cloud .

  5. Salve a configuração.

Claude Code

Embora o plug-in oficial ofereça ferramentas para o Knowledge Catalog, é possível usar a linhagem de dados no Claude Code configurando um servidor local da MCP Toolbox 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 ID do projeto Google Cloud .

  2. Configure o Claude Code para usar o servidor da caixa de ferramentas do MCP:

    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 seu 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 ID do projeto Google Cloud .

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

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

    Substitua PROJECT_ID pelo ID do projeto Google Cloud .

Claude para computador

  1. Abra o Claude para computador e acesse 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 ID do projeto Google Cloud .

  4. Salve a configuração.

  5. Reinicie o Claude para computador. A nova tela de chat mostra um ícone do MCP representando o novo servidor.

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 ID do projeto Google Cloud .

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

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 ID do projeto Google Cloud .

  4. Salve a configuração.

  5. Abra 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 ID do projeto Google Cloud .

  4. Salve a configuração.

Windsurf

  1. Abra o Windsurf e navegue até o assistente do 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 ID do projeto Google Cloud .

  4. Salve a configuração.

Usar as habilidades

Seu 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 para o assistente de IA:

  • 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).
  • Inspecione a linhagem no nível da coluna entre campos específicos em todos os recursos.

Opcional: adicione 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 instruções do sistema com base no comando do sistema recomendado do Data Lineage.

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

  • Quando for 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