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

Para conectar a linhagem de dados a ferramentas de desenvolvedor usando um servidor local da MCP Toolbox, consulte Usar a linhagem de dados com o servidor local da MCP Toolbox.

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 para as 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 comandos. 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 a caixa de ferramentas do MCP 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. Ative a API Dataplex, 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 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 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

Nesta seção, explicamos como conectar o Knowledge Catalog às suas ferramentas.

Para conectar 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. Após a instalação, consulte a seção da sua ferramenta específica para instruções de configuração.

Extensão da CLI do Gemini

Esse método usa a extensão knowledge-catalog 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 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. Nessa pasta, crie um arquivo settings.json.

  4. Adicione a seguinte configuração:

    {
  "mcpServers": {
    "knowledgeCatalog": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","dataplex","--stdio"],
      "env": {
        "DATAPLEX_PROJECT": "PROJECT_ID"
      }
    }
  }
}

    Substitua PROJECT_ID pelo ID do projeto Google Cloud .

  5. Salve a configuração.

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

  3. Inicie o agente:

    claude

  4. Instalar o plug-in:

    /plugin install knowledge-catalog@claude-plugins-official

Codex

  1. Instale o marketplace de plug-ins da Data Cloud:

    codex plugin marketplace add GoogleCloudPlatform/data-cloud-plugins

  2. Instale o plug-in do Knowledge Catalog:

    codex plugin install dataplex@data-cloud-plugins

  3. Configure as variáveis 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. Opcional. Atualize o marketplace:

    codex plugin marketplace upgrade data-cloud-plugins

Claude para computador

  1. Abra o Claude para computador e acesse Configurações.
  2. Para abrir o arquivo de configuração, acesse a guia Desenvolvedor e clique em Editar configuração.

  3. Adicione a seguinte configuração:

    {
  "mcpServers": {
    "knowledgeCatalog": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","dataplex","--stdio"],
      "env": {
        "DATAPLEX_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, clique em Configurar servidores MCP.

  3. Adicione a seguinte configuração:

    {
  "mcpServers": {
    "knowledgeCatalog": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","dataplex","--stdio"],
      "env": {
        "DATAPLEX_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": {
    "knowledgeCatalog": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","dataplex","--stdio"],
      "env": {
        "DATAPLEX_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": {
    "knowledgeCatalog": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","dataplex","--stdio"],
      "env": {
        "DATAPLEX_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": {
    "knowledgeCatalog": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","dataplex","--stdio"],
      "env": {
        "DATAPLEX_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 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. 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 habilidades do Knowledge Catalog:

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