Usar o Knowledge Catalog com o MCP, a CLI do Antigravity e outros agentes

Observação: o Gemini Code Assist e a CLI do Gemini agora são o Antigravity Code Assist e a CLI do Antigravity. Alguns links neste documento apontam para destinos que ainda usam os nomes de produtos antigos.

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

Para conectar a linhagem de dados a ferramentas para desenvolvedores 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 o uso do plug-in dedicado do Knowledge Catalog para a CLI do Antigravity. O plug-in agrupa as habilidades subjacentes diretamente no plug-in, o que simplifica a configuração.

Como alternativa, é possível conectar outros ambientes de desenvolvimento integrado e ferramentas para desenvolvedores que oferecem suporte ao MCP usando uma MCP Toolbox for Databases local. Em seguida, você pode usar 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:

• CLI do Antigravity (por plug-in)
• Antigravity Code Assist
• Claude Code
• Claude para computador
• Codex
• Cline (extensão do VS Code)
• Cursor
• Visual Studio Code (Copilot)
• Windsurf (antigo Codeium)

Sobre a CLI e os plug-ins do Antigravity

A CLI do Antigravity é 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, exploração de dados e criação de conteúdo. Ele oferece uma experiência orientada por agentes para interagir com os serviços do Data Cloud, como o Knowledge Catalog, e outros bancos de dados de código aberto conhecidos.

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

Como funcionam os plug-ins da CLI do Antigravity?

Os plug-ins expandem os recursos da CLI do Antigravity, permitindo que ela se conecte e controle serviços específicos do Google Cloud e outras ferramentas. Eles fornecem à CLI do Antigravity contexto e compreensão da API, permitindo a interação conversacional. É possível carregar plug-ins da CLI do Antigravity de URLs do GitHub, diretórios locais ou registros. Esses plug-ins oferecem novas habilidades, comandos de barra e comandos. Eles são separados dos plug-ins de IDE, como o Antigravity Code Assist, que se integram usando o MCP Toolbox.

Quais ferramentas do MCP o Knowledge Catalog oferece?

O plug-in do Knowledge Catalog para a CLI do Antigravity 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 o plug-in do Knowledge Catalog, consulte o Plug-in da CLI do Antigravity: Knowledge Catalog.

Funções exigidas

Para receber as permissões necessárias para se conectar ao Knowledge Catalog usando o MCP Toolbox ou o plug-in da CLI do Antigravity, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

• Para ativar APIs: Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin)
• Para usar as habilidades do Knowledge Catalog: Leitor do Dataplex Catalog (roles/dataplex.catalogViewer)

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 o plug-in da CLI do Antigravity. 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 o MCP Toolbox ou o plug-in da CLI do Antigravity:

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

   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.
   Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

3. Verifique se o faturamento está ativado para o projeto do Google Cloud .

4. Ative a API Dataplex, se ainda não tiver feito isso.

   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 a MCP Toolbox se você planeja usar apenas o Antigravity Code Assist ou o plug-in da CLI do Antigravity, já que eles incluem 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 versão v0.31.0 ou mais recente do MCP Toolbox.

   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 código aberto do Protocolo de Contexto de Modelo (MCP) que fica entre o 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 ferramenta específica para ver as instruções de configuração.

Observação: não é necessário instalar o MCP Toolbox se você planeja usar apenas o Antigravity Code Assist ou o plug-in da CLI do Antigravity.

Plug-in da CLI do Antigravity

Esse método usa o plug-in knowledge-catalog para a ferramenta de CLI do Antigravity independente e não usa a MCP Toolbox.

1. Instale a CLI do Antigravity.

2. Instale o plug-in do Knowledge Catalog para a CLI do Antigravity no repositório do GitHub:

   agy plugin 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 do Google Cloud.

4. Inicie a CLI do Antigravity no modo interativo:

   agy
   

   A CLI carrega automaticamente o plug-in do Knowledge Catalog e as habilidades dele, que podem ser usadas para interagir com o banco de dados.

5. Na CLI do Antigravity, use o comando /mcp para verificar se o plug-in está instalado.

Antigravity Code Assist

O Antigravity Code Assist inclui os recursos necessários do servidor MCP, então você não precisa instalar o MCP Toolbox separadamente.

1. No VS Code, instale a extensão Antigravity Code Assist.
2. Ative o Modo Agente no chat do Antigravity Code Assist.
3. No diretório de trabalho, crie uma pasta chamada .antigravity. 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 do 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 do Google Cloud.

3. Inicie o agente:

   claude
   

4. Instalar o plug-in:

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

Dica:execute /plugin list no Claude Code para verificar se o plug-in está ativo ou /reload-plugins se você acabou de instalá-lo.

Codex

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

   codex plugin marketplace add GoogleCloudPlatform/data-cloud-plugins
   

2. Instale o plug-in do Catálogo de Conhecimento:

   codex plugin install dataplex@data-cloud-plugins
   

3. Configure as variáveis de ambiente para se conectar ao seu projeto do Knowledge Catalog:

   export DATAPLEX_PROJECT=PROJECT_ID
   

   Substitua PROJECT_ID pelo ID do projeto do Google Cloud.

4. Opcional. Atualize o marketplace:

   codex plugin marketplace upgrade data-cloud-plugins
   

Claude para computador

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

4. Salve a configuração.

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

4. Salve a configuração. Um status ativo verde aparece depois que o servidor é conectado.

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

4. Salve a configuração.

Windsurf

1. Abra o Windsurf e acesse as Configurações 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 do Google Cloud.

4. Salve a configuração.

Usar as habilidades

Seu assistente de IA agora está conectado ao Knowledge Catalog. Peça para o assistente de IA 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: 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, é possível adicionar instruções para orientar o LLM sobre como usar as habilidades do Knowledge Catalog:

• Quando for solicitado que você encontre conjuntos de dados ou tabelas, use a habilidade search_entries.
• Se forem solicitados detalhes do esquema ou dos metadados da tabela, como regras de qualidade de dados ou propriedade, use a habilidade lookup_entry.
• Ao receber perguntas sobre regras ou classificações de governança, comece usando search_aspect_types para encontrar tipos de aspecto relevantes.
• Se responder às perguntas exigir um amplo conjunto de metadados, use a habilidade lookup_context para recuperá-los.

Observação: recomendamos essa etapa opcional para ter uma experiência melhor e evitar trabalho extra, como projetar seu próprio agente.

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

• Saiba como usar o servidor local da MCP Toolbox para linhagem de dados.
• Confira a diferença entre servidores MCP locais e remotos.
• Consulte o caso de uso Usar a CLI do Antigravity para testar o contexto de dados.
• Leia a referência de ferramentas MCP do Knowledge Catalog e a referência de ferramentas MCP da linhagem de dados.
• Pesquisar recursos no Knowledge Catalog.
• Saiba como ingerir fontes personalizadas no Knowledge Catalog.
• Saiba como gerenciar aspectos e enriquecer metadados.