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

Nesta página, explicamos como conectar a instância do Knowledge Catalog (antigo Dataplex Universal Catalog) a ferramentas de desenvolvedor, 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 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 de Protocolo de Contexto de Modelo (MCP, na sigla em inglês) 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, você pode conectar outros ambientes de desenvolvimento integrado 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 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 para as seguintes ferramentas:

Sobre a CLI do Gemini e as extensões

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

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

Como as extensões da CLI do Gemini funcionam?

As extensões expandem os recursos da CLI do Gemini, permitindo que ela se conecte e controle serviços específicos Google Cloud e outras ferramentas. Elas fornecem ao Gemini contexto e compreensão da API, permitindo a interação conversacional. É 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 comandos. Elas são separadas das extensões do ambiente de desenvolvimento integrado, como o Gemini Code Assist, que são integradas usando a MCP Toolbox.

Quais ferramentas MCP o Knowledge Catalog oferece?

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

Categoria Ferramenta Exemplo de comando de 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 informações de identificação pessoal do cliente.
  • Liste todos os conjuntos de dados do BigQuery no 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 aspecto relacionados às regras de qualidade de dados.
  • Liste todos os tipos de aspecto usados para governança de dados.
  • Há algum tipo de aspecto para marcar dados de informações de identificação pessoal?
Embasamento do LLM com contexto lookup_context (preview)
  • Descreva o recurso de dados orders.
  • Crie uma consulta SQL que conte a quantidade de usuários por país.
  • Crie um pipeline de dados que limpe a tabela products.

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

Funções exigidas

Para receber as permissões necessárias para se conectar ao Knowledge Catalog usando a MCP Toolbox 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 MCP Toolbox 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 permissões a seguir são necessárias para se conectar ao Knowledge Catalog usando a 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 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. 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 o MCP Toolbox

Não é necessário instalar a MCP Toolbox se você planeja usar apenas o Gemini Code Assist ou a extensão da CLI do Gemini, porque eles agrupam os recursos de servidor necessários. Para outros ambientes de desenvolvimento integrado 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 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 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

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 independente, não será necessário instalar ou configurar a MCP Toolbox, porque essas ferramentas agrupam os recursos de servidor necessários. Para instruções de configuração, consulte as guias Gemini Code Assist ou Extensão da CLI do Gemini.

Para outras ferramentas e ambientes de desenvolvimento integrado compatíveis com MCP, primeiro instale a MCP Toolbox. A caixa de ferramentas atua como um servidor de Protocolo de Contexto de Modelo (MCP) código aberto que fica entre o ambiente de desenvolvimento integrado e o Knowledge Catalog, fornecendo 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 a 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 Google Cloud projeto.

  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. 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 configuração a seguir, 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 Code

  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 Desktop

  1. Abra 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, 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 Desktop.
    A nova tela de chat mostra um ícone do MCP com 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 configuração a seguir, 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 configuração a seguir, 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 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 não existir.
  2. Crie o arquivo .vscode/mcp.json, se ele não existir, e abra-o.
  3. Adicione a configuração a seguir, 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 acesse o assistente do Cascade.
  2. Para abrir o arquivo de configuração, clique no ícone do MCP e em Configurar.
  3. Adicione a configuração a seguir, 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: pesquisar recursos de dados
  • lookup_entry: recuperar metadados (por exemplo, esquema, uso, visão geral de negócios e contatos) de recursos de dados
  • search_aspect_types: pesquisar tipos de aspecto
  • lookup_context (visualização): recuperar um conjunto de metadados formatados sobre um ou mais recursos de dados

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.

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

  • Quando solicitado a encontrar conjuntos de dados ou tabelas, use a ferramenta search_entries.
  • Se forem solicitados detalhes do esquema da tabela ou 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 aspecto relevantes.
  • Se responder a perguntas exigir um conjunto amplo 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