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 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 as habilidades subjacentes diretamente nela, o que simplifica a configuração.

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 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 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 da CLI do Gemini 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 habilidades, comandos de barra e solicitações. Elas são separadas das extensões do IDE, como o Gemini Code Assist, que se integra usando o MCP Toolbox.

Quais ferramentas da MCP o Knowledge Catalog oferece?

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.

Para conferir todas as habilidades disponíveis, consulte as habilidades do Knowledge Catalog no GitHub.

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 catálogo de dados usando a caixa de ferramentas do MCP ou a extensão da CLI do Gemini, peça que o admin 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 habilidades 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 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 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 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

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

Se você estiver usando o Gemini Code Assist ou a CLI independente 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 de Protocolo de Contexto de Modelo (MCP) de código aberto que fica entre seu IDE e o Knowledge Catalog, fornecendo um plano de controle seguro e eficiente para suas ferramentas de IA. Depois da 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: o ID do projeto do Google Cloud .
  4. Inicie a CLI do Gemini no modo interativo: 
    gemini

    A CLI carrega automaticamente a extensão do Knowledge Catalog e as habilidades dela, que podem ser usadas para interagir com seu banco de dados.

    Na CLI do Gemini, use o comando /extensions para verificar se a extensão está instalada.

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, 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. Defina a variável de ambiente para se conectar ao projeto do Knowledge Catalog: 
    export DATAPLEX_PROJECT="PROJECT_ID"
     Substitua:
    • PROJECT_ID: o ID do projeto do Google Cloud .
  3. Inicie o agente: 
    claude
  4. Instalar o plug-in: 
    /plugin install knowledge-catalog@claude-plugins-official

Codex

  1. Instale o Data Agent Kit no Marketplace: 
    codex plugin marketplace add GoogleCloudPlatform/data-agent-kit
  2. Instale o plug-in do Knowledge Catalog: 
    codex plugin install dataplex@data-agent-kit
  3. Configure as variáveis de ambiente para se conectar ao projeto do Knowledge Catalog: 
    export DATAPLEX_PROJECT="PROJECT_ID"
     Substitua:
    • PROJECT_ID: o ID do projeto do Google Cloud .
  4. Opcional. Atualize o marketplace: 
    codex plugin marketplace upgrade data-agent-kit

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 habilidades

Seu assistente de IA agora está conectado 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.

Para conferir todas as habilidades disponíveis, consulte as habilidades do Knowledge Catalog no GitHub.

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 de sistema recomendado.

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

  • Quando for solicitado a encontrar conjuntos de dados ou tabelas, use a habilidade search_entries.
  • Se você precisar de detalhes sobre o esquema da tabela ou metadados, como regras de qualidade de dados ou propriedade, use a capacidade lookup_entry.
  • Quando perguntarem 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 habilidade 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