Use Knowledge Catalog with MCP, the Antigravity CLI, and other agents

Note: Gemini Code Assist and the Gemini CLI are now Antigravity Code Assist and the Antigravity CLI. Some links in this document point to destinations that still use the former product names.

This page explains how to connect your Knowledge Catalog (formerly Dataplex Universal Catalog) instance to developer tools such as the Antigravity CLI. Connecting Knowledge Catalog to these tools enables AI-driven data discovery and asset management directly within your tool.

To connect data lineage to developer tools using a local MCP Toolbox server, see Use data lineage with local MCP Toolbox server.

For an integrated command-line experience, we recommend using the dedicated Knowledge Catalog plugin for the Antigravity CLI. The plugin bundles the underlying skills directly into the plugin, which simplifies setup and configuration.

Alternatively, you can connect other IDEs and developer tools that support MCP by using a local MCP Toolbox for Databases. You can then use AI agents in your existing IDE to discover data assets in Knowledge Catalog. For more information about MCP, see Introduction to Model Context Protocol.

This guide demonstrates the connection process for the following tools:

• Antigravity CLI (through plugin)
• Antigravity Code Assist
• Claude Code
• Claude desktop
• Codex
• Cline (VS Code extension)
• Cursor
• Visual Studio Code (Copilot)
• Windsurf (formerly Codeium)

About the Antigravity CLI and plugins

The Antigravity CLI is an open-source conversational AI agent from Google that accelerates development workflows and assists with coding, debugging, data exploration, and content creation. It offers an agent-driven experience to interact with Data Cloud services, such as Knowledge Catalog, and other popular open-source databases.

For more information about the Antigravity CLI, see the Antigravity CLI documentation.

How do Antigravity CLI plugins work?

Plugins expand the capabilities of the Antigravity CLI, letting it connect to and control specific Google Cloud services and other tools. They provide the Antigravity CLI with context and API understanding, enabling conversational interaction. You can load Antigravity CLI plugins from GitHub URLs, local directories, or registries. These plugins offer new skills, slash commands, and prompts. These are separate from IDE plugins, such as Antigravity Code Assist, which integrate using the MCP Toolbox.

What MCP tools does Knowledge Catalog provide?

The Knowledge Catalog plugin for the Antigravity CLI integrates AI into your data governance and discovery tasks. You can interact with Knowledge Catalog using natural language prompts in your terminal.

For all available skills, see the Knowledge Catalog skills on GitHub.

For more information about the Knowledge Catalog plugin, see the Antigravity CLI Plugin - Knowledge Catalog.

Required roles

To get the permissions that you need to connect to Knowledge Catalog using MCP Toolbox or the Antigravity CLI plugin, ask your administrator to grant you the following IAM roles on your project:

• To enable APIs: Service Usage Admin (roles/serviceusage.serviceUsageAdmin)
• To use Knowledge Catalog skills: Dataplex Catalog Viewer (roles/dataplex.catalogViewer)

For more information about granting roles, see Manage access to projects, folders, and organizations.

These predefined roles contain the permissions required to connect to Knowledge Catalog using MCP Toolbox or the Antigravity CLI plugin. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to connect to Knowledge Catalog using MCP Toolbox or the Antigravity CLI plugin:

• To enable APIs: serviceusage.services.enable
• To use Knowledge Catalog skills:
  • dataplex.projects.search
  • dataplex.entries.get
  • dataplex.aspectTypes.get
  • dataplex.aspectTypes.list

You might also be able to get these permissions with custom roles or other predefined roles.

Enable the Dataplex API

1. In the Google Cloud console, go to the project selector page.

   Go to project selector

2. Select or create a Google Cloud project.

   Roles required to select or create a project

   • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
   • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.
   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

3. Verify that billing is enabled for your Google Cloud project.

4. Enable the Dataplex API, if it is not already enabled.

   Roles required to enable APIs

   To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

   Enable the API

5. If you're using a local shell, then create local authentication credentials for your user account:

   gcloud auth application-default login

   You don't need to do this if you're using Cloud Shell.

   If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

Install MCP Toolbox

You don't need to install MCP Toolbox if you only plan to use Antigravity Code Assist or the Antigravity CLI plugin, as they bundle the required server capabilities. For other IDEs and tools, follow the steps in this section to install MCP Toolbox.

1. Download the latest version of MCP Toolbox as a binary. Select the MCP Toolbox binary release that corresponds to your (OS) and CPU architecture. You must use MCP Toolbox v0.31.0 or later.

   Linux/amd64

   curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/VERSION/linux/amd64/toolbox

   Replace VERSION with MCP Toolbox version—for example, v0.31.0.

   macOS (Darwin)/arm64

   curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/VERSION/darwin/arm64/toolbox

   Replace VERSION with MCP Toolbox version—for example, v0.31.0.

   macOS (Darwin)/amd64

   curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/VERSION/darwin/amd64/toolbox

   Replace VERSION with MCP Toolbox version—for example, v0.31.0.

   Windows/amd64

   curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/VERSION/windows/amd64/toolbox

   Replace VERSION with MCP Toolbox version—for example, v0.31.0.

2. Make the binary executable:

   chmod +x toolbox
   

3. Verify the installation:

   ./toolbox --version
   

   A successful installation returns the version number, for example, 0.15.0.

Set up clients and connections

This section explains how to connect Knowledge Catalog to your tools.

To connect MCP-compatible tools and IDEs, you must first install MCP Toolbox. The toolbox acts as an open-source Model Context Protocol (MCP) server that sits between your IDE and Knowledge Catalog, providing a secure and efficient control plane for your AI tools. After installation, see the section for your specific tool for configuration instructions.

Note: You don't need to install MCP Toolbox if you only plan to use Antigravity Code Assist or the Antigravity CLI plugin.

Antigravity CLI plugin

This method uses the knowledge-catalog plugin for the standalone Antigravity CLI tool, and doesn't use MCP Toolbox.

1. Install the Antigravity CLI.

2. Install the Knowledge Catalog plugin for the Antigravity CLI from the GitHub repository:

   agy plugin install https://github.com/gemini-cli-extensions/knowledge-catalog
   

3. Set the environment variable to connect to your Knowledge Catalog project:

   export DATAPLEX_PROJECT=PROJECT_ID
   

   Replace PROJECT_ID with the Google Cloud project ID.

4. Start the Antigravity CLI in interactive mode:

   agy
   

   The CLI automatically loads the Knowledge Catalog plugin and its skills, which you can use to interact with your database.

5. In the Antigravity CLI, use the /mcp command to verify that the plugin is installed.

Antigravity Code Assist

Antigravity Code Assist bundles the required MCP server capabilities, so you don't need to install MCP Toolbox separately.

1. In VS Code, install the Antigravity Code Assist extension.
2. Enable Agent Mode in Antigravity Code Assist chat.
3. In your working directory, create a folder named .antigravity. Within that folder, create a settings.json file.

4. Add the following configuration:

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

   Replace PROJECT_ID with the Google Cloud project ID.

5. Save the configuration.

Claude Code

1. Install Claude Code.

2. Set the environment variable to connect to your Knowledge Catalog project:

   export DATAPLEX_PROJECT=PROJECT_ID
   

   Replace PROJECT_ID with the Google Cloud project ID.

3. Start the agent:

   claude
   

4. Install the plugin:

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

Tip: Run /plugin list inside Claude Code to verify the plugin is active, or /reload-plugins if you just installed it.

Codex

1. Install the Data Cloud Plugins marketplace:

   codex plugin marketplace add GoogleCloudPlatform/data-cloud-plugins
   

2. Install the Knowledge Catalog plugin:

   codex plugin install dataplex@data-cloud-plugins
   

3. Configure the environment variables to connect to your Knowledge Catalog project:

   export DATAPLEX_PROJECT=PROJECT_ID
   

   Replace PROJECT_ID with the Google Cloud project ID.

4. Optional. Update the marketplace:

   codex plugin marketplace upgrade data-cloud-plugins
   

Claude desktop

1. Open Claude Desktop and navigate to Settings.
2. To open the configuration file, go to the Developer tab and click Edit config.

3. Add the following configuration:

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

   Replace PROJECT_ID with the Google Cloud project ID.

4. Save the configuration.

5. Restart Claude desktop. The new chat screen displays an MCP icon representing the new MCP server.

Cline

1. In VS Code, open the Cline extension and then click the MCP Servers icon.
2. To open the configuration file, click Configure MCP Servers.

3. Add the following configuration:

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

   Replace PROJECT_ID with the Google Cloud project ID.

4. Save the configuration. A green active status appears after the server connects successfully.

Cursor

1. Create the .cursor directory in your project root if it doesn't exist.
2. Create the .cursor/mcp.json file if it doesn't exist and open it.

3. Add the following configuration:

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

   Replace PROJECT_ID with the Google Cloud project ID.

4. Save the configuration.

5. Open Cursor and navigate to Settings > Cursor Settings > MCP. A green active status appears when the server connects.

VS Code (Copilot)

1. Open VS Code and create .vscode directory in your project root if it doesn't exist.
2. Create the .vscode/mcp.json file if it doesn't exist, and open it.

3. Add the following configuration:

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

   Replace PROJECT_ID with the Google Cloud project ID.

4. Save the configuration.

Windsurf

1. Open Windsurf and navigate to Cascade Settings.
2. To open the configuration file, click the MCP icon, then click Configure.

3. Add the following configuration:

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

   Replace PROJECT_ID with the Google Cloud project ID.

4. Save the configuration.

Use the skills

Your AI assistant is now connected to Knowledge Catalog. Try asking your AI assistant to find some data assets such as BigQuery datasets, Cloud SQL instances, and others.

For all available skills, see the Knowledge Catalog skills on GitHub.

Optional: Add system instructions

System instructions are a way to provide specific guidelines to the LLM, helping it to understand the context and respond more accurately. Set up system instructions based on the recommended system prompt.

For example, you can add instructions to guide the LLM on how to use the Knowledge Catalog skills:

• When asked to find datasets or tables, use the search_entries skill.
• If asked for table schema or metadata details such as data quality rules or ownership, use the lookup_entry skill.
• When asked about governance rules or classifications, start by using search_aspect_types to find relevant aspect types.
• If answering questions requires broad set of metadata, use the lookup_context skill to retrieve it.

Note: We recommend this optional step to get a better experience and avoid additional work, for example, designing your own agent.

For more information about how to configure instructions, see Use instructions to get AI edits that follow your coding style.

What's next

• Learn how to use the local MCP Toolbox server for data lineage.
• Review the difference between local and remote MCP servers.
• See the Use the Antigravity CLI to test data context use case.
• Read the Knowledge Catalog MCP tools reference and Data Lineage MCP tools reference.
• Search for resources in Knowledge Catalog.
• Learn how to ingest custom sources into Knowledge Catalog.
• Learn how to manage aspects and enrich metadata.