Usar linhagem de dados com MCP, Gemini e outros agentes

Nesta página, explicamos 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). A conexão da linhagem de dados a essas ferramentas permite o rastreamento de linhagem orientado por IA e a análise de proveniência de dados diretamente no seu ambiente de desenvolvimento.

É possível conectar ambientes de desenvolvimento integrado e ferramentas para desenvolvedores compatíveis com o MCP usando uma MCP Toolbox for Databases local. Em seguida, você pode usar agentes de IA no seu ambiente de desenvolvimento integrado para consultar gráficos de linhagem de dados, descobrir a proveniê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 para as 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 os recursos de origem (upstream) e de destino (downstream). Ele é compatível com a 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 o 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 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 o MCP Toolbox:

  • 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 .

    Papéis necessários para selecionar ou criar um projeto

    • Selecionar um projeto: para selecionar um projeto, não é necessário ter um papel do IAM específico. É possível selecionar qualquer projeto em que você tenha um papel.
    • Criar um projeto: para criar um projeto, é preciso 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 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 pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo 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 externo (IdP), confirme se você fez login na CLI gcloud com sua identidade federada.

Instalar o MCP Toolbox

Não é necessário instalar o MCP Toolbox se você planeja usar apenas o Gemini Code Assist, já que ele inclui os recursos de servidor necessários. Para outros ambientes de desenvolvimento integrado e ferramentas, siga as etapas nesta seção para instalar o MCP Toolbox.

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

    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

Nesta seção, explicamos 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 fonte 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 do Google Cloud :

    export DATALINEAGE_PROJECT=PROJECT_ID

    Substitua PROJECT_ID pelo ID do projeto do 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 do 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 inclui 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 na conversa do Gemini Code Assist.
  3. No diretório de trabalho, crie uma pasta chamada .gemini. Dentro dele, 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 do 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 do Google Cloud .

  2. Configure o Claude Code para usar o servidor da 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 o 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 do Google Cloud .

  2. Na configuração do MCP do Codex, adicione o servidor usando o 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 ID do projeto do Google Cloud .

Claude para computador

  1. Abra o Claude Desktop 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 do Google Cloud .

  4. Salve a configuração.

  5. Reinicie o Claude para computador. A nova tela de chat mostra um ícone de 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 ID do projeto do 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 ainda 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 do Google Cloud .

  4. Salve a configuração.

  5. Abra o Cursor e acesse 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 ainda 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 do Google Cloud .

  4. Salve a configuração.

Windsurf

  1. Abra o Windsurf e acesse 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 ID do projeto do 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).
  • Descubra 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: 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 pela linhagem de dados.

Por exemplo, é possível adicionar instruções para orientar o LLM sobre como usar as habilidades de linhagem de dados:

  • Quando for solicitado que você rastreie 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