Usar o catálogo de conhecimento com o MCP, o Gemini e outros agentes

Nesta página, explicamos como conectar sua instância do Knowledge Catalog (antigo Dataplex Universal Catalog) a ferramentas para desenvolvedores, como a CLI do Gemini. Ao conectar o Knowledge Catalog a essas ferramentas, você ativa a descoberta de dados e o gerenciamento de recursos com tecnologia de IA diretamente na sua ferramenta.

Para uma experiência integrada de linha de comando, recomendamos usar a extensão dedicada do Knowledge Catalog para a CLI do Gemini. A extensão agrupa um servidor do Protocolo de Contexto de Modelo (MCP) subjacente, que atua como um intermediário entre a CLI do Gemini e o Knowledge Catalog, eliminando a necessidade de uma configuração de servidor separada.

Como alternativa, conecte outros ambientes de desenvolvimento integrado (IDEs) e ferramentas para desenvolvedores que oferecem suporte ao MCP usando uma MCP Toolbox for Databases local. Em seguida, use agentes de IA no seu IDE existente para descobrir recursos de dados no Knowledge Catalog. 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:

Sobre a CLI do Gemini e as extensões

A CLI do Gemini é um agente de IA de conversação de código aberto do Google que acelera os fluxos de trabalho de desenvolvimento e ajuda na programação, depuração, análise de dados e criação de conteúdo. Ele oferece uma experiência orientada por agente para interagir com os serviços da Data Cloud, como o Knowledge Catalog, e outros bancos de dados de código aberto conhecidos.

Para mais informações sobre a CLI do Gemini, consulte a documentação da CLI do Gemini.

Como as extensões funcionam

As extensões ampliam os recursos da CLI do Gemini, permitindo que ela se conecte e controle serviços Google Cloud específicos e outras ferramentas. Eles fornecem contexto e compreensão da API ao Gemini, permitindo a interação por conversa. É possível carregar extensões da CLI do Gemini de URLs do GitHub, diretórios locais ou registros. Essas extensões oferecem novas ferramentas, comandos de barra e solicitações. Elas são separadas das extensões do IDE, como o Gemini Code Assist, que se integram usando o MCP Toolbox.

Sobre a extensão do Knowledge Catalog

A extensão do Knowledge Catalog para a CLI do Gemini integra a IA às suas tarefas de governança e descoberta de dados. Você pode interagir com o Knowledge Catalog usando comandos em linguagem natural no terminal. Confira alguns exemplos:

Categoria Ferramenta Exemplo de comando em linguagem natural
Descoberta e governança de dados search_entries
  • Encontre todos os conjuntos de dados relacionados a vendas na Europa.
  • Mostre as tabelas que contêm PIIs de clientes.
  • Liste todos os conjuntos de dados do BigQuery no data lake marketing no Knowledge Catalog.
lookup_entry
  • Qual é o esquema da tabela orders?
  • Descreva as regras de qualidade de dados aplicadas ao banco de dados customer.
  • Quem está listado como proprietário da empresa na tabela customer_details?
search_aspect_types
  • Mostre os tipos de aspectos relacionados às regras de qualidade de dados.
  • Liste todos os tipos de aspectos usados para governança de dados.
  • Existem tipos de aspectos para marcar dados de PII?
Embasamento de LLM com contexto lookup_context (preview)
  • Descreva o recurso de dados orders.
  • Escreva uma consulta SQL que conte a quantidade de usuários por país.
  • Gravar pipeline de dados limpando a tabela products.

Para mais informações sobre a extensão do Knowledge Catalog, consulte Extensão da CLI do Gemini: Knowledge Catalog.

Funções exigidas

Para receber as permissões necessárias a fim de se conectar ao Knowledge Catalog usando a caixa de ferramentas do MCP ou a extensão da CLI do Gemini, peça que o administrador conceda 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 ao Knowledge Catalog usando a caixa de ferramentas do MCP ou a extensão da CLI do Gemini. 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 ao Knowledge Catalog usando o MCP Toolbox ou a extensão da CLI do Gemini:

  • Para ativar as APIs: serviceusage.services.enable
  • Para usar as ferramentas do Knowledge Catalog:
    • dataplex.projects.search
    • dataplex.entries.get
    • dataplex.aspectTypes.get
    • dataplex.aspectTypes.list

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

Ativar a API Dataplex

  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. Ativar a API Dataplex

    Funções necessárias para ativar APIs

    Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. 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 a MCP Toolbox

Não é necessário instalar o MCP Toolbox se você planeja usar apenas o Gemini Code Assist ou a extensão da CLI do Gemini, já que eles incluem 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 binário que corresponde ao seu sistema operacional 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 caixa de ferramentas do MCP. 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 caixa de ferramentas do MCP. 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 caixa de ferramentas do MCP. 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 caixa de ferramentas do MCP. 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

Esta seção explica como conectar o Knowledge Catalog às suas ferramentas.

Se você estiver usando o Gemini Code Assist ou a CLI do Gemini, não será necessário instalar nem configurar a caixa de ferramentas do MCP, já que essas ferramentas incluem os recursos necessários do servidor. Para instruções de configuração, consulte as guias "Gemini Code Assist" ou "extensão da CLI do Gemini".

Para outras ferramentas e IDEs compatíveis com o MCP, primeiro instale o MCP Toolbox. A caixa de ferramentas funciona como um servidor Protocolo de Contexto de Modelo (MCP) de código aberto que fica entre seu ambiente de desenvolvimento integrado (IDE) e o Knowledge Catalog, oferecendo um plano de controle seguro e eficiente para suas ferramentas de IA. Após a instalação, selecione a guia da sua ferramenta específica para conferir as instruções de configuração.

Extensão da CLI do Gemini

Esse método usa a extensão knowledge-catalog dedicada para a ferramenta independente da CLI do Gemini e não usa o MCP Toolbox.

  1. Instale a CLI do Gemini.
  2. Instale a extensão do Knowledge Catalog para a CLI do Gemini no repositório do GitHub: 
    gemini extensions install https://github.com/gemini-cli-extensions/knowledge-catalog
  3. Defina a variável de ambiente para se conectar ao projeto do Knowledge Catalog: 
    export DATAPLEX_PROJECT="PROJECT_ID"

    Substitua PROJECT_ID pelo ID do projeto Google Cloud .

  4. Inicie a CLI do Gemini no modo interativo: 
    gemini
     A CLI carrega automaticamente a extensão do Knowledge Catalog e as ferramentas dela, que você pode usar para interagir com seus recursos de dados.

Gemini Code Assist

O Gemini Code Assist agrupa os recursos necessários do servidor MCP, então não é preciso instalar a 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, substitua as variáveis de ambiente pelos seus valores e salve: 
      {
    "mcpServers": {
      "knowledgeCatalog": {
        "command": "./PATH/TO/toolbox",
        "args": ["--prebuilt","dataplex","--stdio"],
        "env": {
          "DATAPLEX_PROJECT": "PROJECT_ID"
        }
      }
    }
  }

Código do Claude

  1. Instale o Claude Code.
  2. Crie o arquivo .mcp.json na raiz do projeto, se ele não existir.
  3. Adicione a configuração, substitua as variáveis de ambiente pelos seus valores e salve: 
      {
    "mcpServers": {
      "knowledgeCatalog": {
        "command": "./PATH/TO/toolbox",
        "args": ["--prebuilt","dataplex","--stdio"],
        "env": {
          "DATAPLEX_PROJECT": "PROJECT_ID"
        }
      }
    }
  }

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, substitua as variáveis de ambiente pelos seus valores e salve: 
      {
    "mcpServers": {
      "knowledgeCatalog": {
        "command": "./PATH/TO/toolbox",
        "args": ["--prebuilt","dataplex","--stdio"],
        "env": {
          "DATAPLEX_PROJECT": "PROJECT_ID"
        }
      }
    }
  }
  4. Reinicie o Claude para computador.
    A nova tela de chat mostra um ícone do MCP com 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, substitua as variáveis de ambiente pelos seus valores e salve: 
      {
    "mcpServers": {
      "knowledgeCatalog": {
        "command": "./PATH/TO/toolbox",
        "args": ["--prebuilt","dataplex","--stdio"],
        "env": {
          "DATAPLEX_PROJECT": "PROJECT_ID"
        }
      }
    }
  }
    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, substitua as variáveis de ambiente pelos seus valores e salve: 
      {
    "mcpServers": {
      "knowledgeCatalog": {
        "command": "./PATH/TO/toolbox",
        "args": ["--prebuilt","dataplex","--stdio"],
        "env": {
          "DATAPLEX_PROJECT": "PROJECT_ID"
        }
      }
    }
  }
  4. 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, substitua as variáveis de ambiente pelos seus valores e salve: 
      {
    "servers": {
      "knowledgeCatalog": {
        "command": "./PATH/TO/toolbox",
        "args": ["--prebuilt","dataplex","--stdio"],
        "env": {
          "DATAPLEX_PROJECT": "PROJECT_ID"
        }
      }
    }
  }

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, substitua as variáveis de ambiente pelos seus valores e salve: 
      {
    "mcpServers": {
      "knowledgeCatalog": {
        "command": "./PATH/TO/toolbox",
        "args": ["--prebuilt","dataplex","--stdio"],
        "env": {
          "DATAPLEX_PROJECT": "PROJECT_ID"
        }
      }
    }
  }

Usar as ferramentas

Sua ferramenta de IA agora está conectada ao Knowledge Catalog. Peça ao assistente de IA para encontrar alguns recursos de dados, como conjuntos de dados do BigQuery, instâncias do Cloud SQL e outros.

As seguintes ferramentas estão disponíveis para o LLM:

  • search_entries: pesquisa de recursos de dados
  • lookup_entry: recupera metadados (por exemplo, esquema, uso, visão geral da empresa e contatos) de recursos de dados.
  • search_aspect_types: pesquisa por tipos de aspecto
  • lookup_context (prévia): recupera um conjunto avançado de metadados pré-formatados sobre um ou mais recursos de dados.

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. Defina instruções do sistema com base no comando de sistema recomendado.

Por exemplo, você pode adicionar instruções para orientar o LLM sobre como usar as ferramentas do Knowledge Catalog:

  • Quando for solicitado a encontrar conjuntos de dados ou tabelas, use a ferramenta search_entries.
  • Se for solicitado o esquema da tabela ou detalhes de metadados, como regras de qualidade de dados ou propriedade, use a ferramenta lookup_entry.
  • Quando perguntado sobre regras ou classificações de governança, comece usando search_aspect_types para encontrar tipos de aspectos relevantes.
  • Se responder a perguntas exigir um amplo conjunto de metadados, use a ferramenta lookup_context para recuperá-los.

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