Usa Knowledge Catalog con MCP, la CLI de Antigravity y otros agentes

En esta página, se explica cómo conectar tu instancia de Knowledge Catalog (antes llamado Dataplex Universal Catalog) a herramientas para desarrolladores, como la CLI de Antigravity. Conectar Knowledge Catalog a estas herramientas permite el descubrimiento de datos y la administración de recursos impulsados por IA directamente en tu herramienta.

Para conectar el linaje de datos a las herramientas para desarrolladores con un servidor local de MCP Toolbox, consulta Usa el linaje de datos con el servidor local de MCP Toolbox.

Para obtener una experiencia de línea de comandos integrada, te recomendamos que uses el complemento dedicado de Knowledge Catalog para la CLI de Antigravity. El complemento agrupa las habilidades subyacentes directamente en el complemento, lo que simplifica la configuración.

Como alternativa, puedes conectar otros IDEs y herramientas para desarrolladores que admitan MCP con una instancia local de MCP Toolbox para bases de datos. Luego, puedes usar agentes de IA en tu IDE existente para descubrir recursos de datos en Knowledge Catalog. Para obtener más información sobre el MCP, consulta Introducción al Protocolo de contexto del modelo.

En esta guía, se muestra el proceso de conexión para las siguientes herramientas:

Acerca de la CLI de Antigravity y los complementos

La CLI de Antigravity es un agente de IA conversacional de código abierto de Google que acelera los flujos de trabajo de desarrollo y ayuda con la programación, la depuración, la exploración de datos y la creación de contenido. Ofrece una experiencia basada en agentes para interactuar con los servicios de Data Cloud, como Knowledge Catalog, y otras bases de datos de código abierto populares.

Para obtener más información sobre la CLI de Antigravity, consulta la documentación de la CLI de Antigravity.

¿Cómo funcionan los complementos de la CLI de Antigravity?

Los complementos expanden las capacidades de la CLI de Antigravity, lo que le permite conectarse a servicios de Google Cloud y otras herramientas, y controlarlos. Proporcionan a la CLI de Antigravity comprensión de la API y el contexto, lo que permite la interacción conversacional. Puedes cargar complementos de la CLI de Antigravity desde URLs de GitHub, directorios locales o registros. Estos complementos ofrecen nuevas habilidades, comandos de barra y mensajes. Estos son independientes de los complementos del IDE, como Antigravity Code Assist, que se integran con MCP Toolbox.

¿Qué herramientas de MCP proporciona Knowledge Catalog?

El complemento de Knowledge Catalog para la CLI de Antigravity integra la IA en tus tareas de administración y descubrimiento de datos. Puedes interactuar con Knowledge Catalog usando instrucciones en lenguaje natural en tu terminal.

Para conocer todas las habilidades disponibles, consulta las habilidades del Knowledge Catalog en GitHub.

Para obtener más información sobre el complemento de Knowledge Catalog, consulta el complemento de la CLI de Antigravity: Knowledge Catalog.

Roles obligatorios

Para obtener los permisos que necesitas para conectarte a Knowledge Catalog con MCP Toolbox o el complemento de la CLI de Antigravity, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Estos roles predefinidos contienen los permisos necesarios para conectarse a Knowledge Catalog con MCP Toolbox o el complemento de la CLI de Antigravity. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para conectarse a Knowledge Catalog con MCP Toolbox o el complemento de la CLI de Antigravity:

  • Para habilitar las APIs, haz lo siguiente: serviceusage.services.enable
  • Para usar las habilidades de Knowledge Catalog, haz lo siguiente:
    • dataplex.projects.search
    • dataplex.entries.get
    • dataplex.aspectTypes.get
    • dataplex.aspectTypes.list

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Habilitar la API de Dataplex

  1. En la consola de Google Cloud , ve a la página del selector de proyectos.

    Ir al selector de proyectos

  2. Selecciona o crea un proyecto de Google Cloud .

    Roles necesarios para seleccionar o crear un proyecto

    • Selecciona un proyecto: Para seleccionar un proyecto, no se requiere un rol de IAM específico. Puedes seleccionar cualquier proyecto en el que se te haya otorgado un rol.
    • Crea un proyecto: Para crear un proyecto, necesitas el rol de creador de proyectos (roles/resourcemanager.projectCreator), que contiene el permiso resourcemanager.projects.create. Obtén más información para otorgar roles.

  3. Verifica que la facturación esté habilitada para tu proyecto de Google Cloud .

  4. Habilita la API de Dataplex si aún no está habilitada.

    Roles necesarios para habilitar las APIs

    Para habilitar las APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtenerlo a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén información para otorgar roles.

    Habilitar la API

  5. Si usas una shell local, crea credenciales de autenticación locales para tu cuenta de usuario: 

    gcloud auth application-default login

    No es necesario que lo hagas si usas Cloud Shell.

    Si se muestra un error de autenticación y usas un proveedor de identidad externo (IdP), confirma que accediste a gcloud CLI con tu identidad federada.

Instala MCP Toolbox

No es necesario que instales MCP Toolbox si solo planeas usar Antigravity Code Assist o el complemento de la CLI de Antigravity, ya que incluyen las capacidades de servidor requeridas. Para otros IDEs y herramientas, sigue los pasos de esta sección para instalar MCP Toolbox.

  1. Descarga la versión más reciente de MCP Toolbox como un objeto binario. Selecciona la versión binaria de MCP Toolbox que corresponda a tu SO y arquitectura de la CPU. Debes usar MCP Toolbox v0.31.0 o una versión posterior.

    Linux/amd64

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

    Reemplaza VERSION por la versión de MCP Toolbox, por ejemplo, v0.31.0.

    macOS (Darwin)/arm64

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

    Reemplaza VERSION por la versión de MCP Toolbox, por ejemplo, v0.31.0.

    macOS (Darwin)/amd64

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

    Reemplaza VERSION por la versión de MCP Toolbox, por ejemplo, v0.31.0.

    Windows/amd64

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

    Reemplaza VERSION por la versión de MCP Toolbox, por ejemplo, v0.31.0.

  2. Haz que el objeto binario sea ejecutable:

    chmod +x toolbox

  3. Verifica la instalación:

    ./toolbox --version

    Si la instalación se realiza correctamente, se muestra el número de versión, por ejemplo, 0.15.0.

Configura clientes y conexiones

En esta sección, se explica cómo conectar Knowledge Catalog a tus herramientas.

Para conectar herramientas y entornos de desarrollo integrado (IDE) compatibles con MCP, primero debes instalar MCP Toolbox. La caja de herramientas actúa como un servidor de Protocolo de contexto del modelo (MCP) de código abierto que se encuentra entre tu IDE y Knowledge Catalog, lo que proporciona un plano de control seguro y eficiente para tus herramientas de IA. Después de la instalación, consulta la sección de tu herramienta específica para obtener instrucciones de configuración.

Complemento de la CLI de Antigravity

Este método usa el complemento knowledge-catalog para la herramienta independiente de la CLI de Antigravity y no usa MCP Toolbox.

  1. Instala la CLI de Antigravity.

  2. Instala el complemento de Knowledge Catalog para la CLI de Antigravity desde el repositorio de GitHub:

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

  3. Establece la variable de entorno para conectarte a tu proyecto de Knowledge Catalog:

    export DATAPLEX_PROJECT=PROJECT_ID

    Reemplaza PROJECT_ID por el ID del proyecto de Google Cloud.

  4. Inicia la CLI de Antigravity en modo interactivo:

    agy

    La CLI carga automáticamente el complemento de Knowledge Catalog y sus habilidades, que puedes usar para interactuar con tu base de datos.

  5. En la CLI de Antigravity, usa el comando /mcp para verificar que el complemento esté instalado.

Antigravity Code Assist

Antigravity Code Assist incluye las capacidades de servidor de MCP necesarias, por lo que no necesitas instalar MCP Toolbox por separado.

  1. En VS Code, instala la extensión Antigravity Code Assist.
  2. Habilitar el Modo de agente en el chat de Antigravity Code Assist
  3. En tu directorio de trabajo, crea una carpeta llamada .antigravity. Dentro de esa carpeta, crea un archivo settings.json.

  4. Agrega la siguiente configuración:

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

    Reemplaza PROJECT_ID por el ID del proyecto de Google Cloud.

  5. Guarde la configuración.

Claude Code

  1. Instala Claude Code.

  2. Establece la variable de entorno para conectarte a tu proyecto de Knowledge Catalog:

    export DATAPLEX_PROJECT=PROJECT_ID

    Reemplaza PROJECT_ID por el ID del proyecto de Google Cloud.

  3. Inicia el agente:

    claude

  4. Instala el complemento:

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

Codex

Para usar Knowledge Catalog en Codex, configura una conexión de servidor de MCP en tu configuración de Codex para ejecutar MCP Toolbox:

  1. Establece la variable de entorno para conectarte a tu proyecto de Knowledge Catalog:

    export DATAPLEX_PROJECT=PROJECT_ID

    Reemplaza PROJECT_ID por el ID del proyecto de Google Cloud.

  2. En tu configuración de Codex MCP, agrega el servidor con MCP Toolbox:

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

    Reemplaza PROJECT_ID por el ID del proyecto de Google Cloud.

Claude para computadoras de escritorio

  1. Abre Claude Desktop y navega a Configuración.
  2. Para abrir el archivo de configuración, ve a la pestaña Desarrollador y haz clic en Editar configuración.

  3. Agrega la siguiente configuración:

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

    Reemplaza PROJECT_ID por el ID del proyecto de Google Cloud.

  4. Guarde la configuración.

  5. Reinicia Claude para computadoras. La nueva pantalla de chat muestra un ícono de MCP que representa el nuevo servidor de MCP.

Cline

  1. En VS Code, abre la extensión Cline y, luego, haz clic en el ícono de servidores de MCP.
  2. Para abrir el archivo de configuración, haz clic en Configurar servidores de MCP.

  3. Agrega la siguiente configuración:

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

    Reemplaza PROJECT_ID por el ID del proyecto de Google Cloud.

  4. Guarde la configuración. Aparecerá un estado activo de color verde después de que el servidor se conecte correctamente.

Cursor

  1. Crea el directorio .cursor en la raíz del proyecto si no existe.
  2. Crea el archivo .cursor/mcp.json si no existe y ábrelo.

  3. Agrega la siguiente configuración:

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

    Reemplaza PROJECT_ID por el ID del proyecto de Google Cloud.

  4. Guarde la configuración.

  5. Abre Cursor y navega a Settings > Cursor Settings > MCP. Cuando el servidor se conecte, aparecerá un estado activo de color verde.

VS Code (Copilot)

  1. Abre VS Code y crea el directorio .vscode en la raíz del proyecto si no existe.
  2. Crea el archivo .vscode/mcp.json si no existe y ábrelo.

  3. Agrega la siguiente configuración:

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

    Reemplaza PROJECT_ID por el ID del proyecto de Google Cloud.

  4. Guarde la configuración.

Windsurf

  1. Abre Windsurf y navega a Cascade Settings.
  2. Para abrir el archivo de configuración, haz clic en el ícono de MCP y, luego, en Configurar.

  3. Agrega la siguiente configuración:

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

    Reemplaza PROJECT_ID por el ID del proyecto de Google Cloud.

  4. Guarde la configuración.

Usa las habilidades

Tu asistente de IA ahora está conectado a Knowledge Catalog. Pídele a tu asistente de IA que busque algunos recursos de datos, como conjuntos de datos de BigQuery, instancias de Cloud SQL y otros.

Para ver todas las habilidades disponibles, consulta las habilidades del catálogo de conocimientos en GitHub.

Opcional: Agrega instrucciones del sistema

Las instrucciones del sistema son una forma de proporcionar lineamientos específicos al LLM, lo que lo ayuda a comprender el contexto y responder con mayor precisión. Configura las instrucciones del sistema en función de la instrucción del sistema recomendada.

Por ejemplo, puedes agregar instrucciones para guiar al LLM sobre cómo usar las habilidades del Knowledge Catalog:

  • Cuando se te pida que busques conjuntos de datos o tablas, usa la habilidad search_entries.
  • Si se te solicita el esquema de la tabla o detalles de los metadatos, como las reglas de calidad de los datos o la propiedad, usa la habilidad lookup_entry.
  • Cuando se te pregunte sobre las reglas o clasificaciones de administración, comienza por usar search_aspect_types para encontrar tipos de aspectos relevantes.
  • Si responder preguntas requiere un amplio conjunto de metadatos, usa la habilidad de lookup_context para recuperarlos.

Para obtener más información sobre cómo configurar las instrucciones, consulta Usa instrucciones para obtener ediciones de IA que sigan tu estilo de programación.

¿Qué sigue?