Usa Knowledge Catalog con MCP, Gemini y otros agentes

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

Para obtener una experiencia integrada de línea de comandos, te recomendamos que uses la extensión dedicada de Knowledge Catalog para Gemini CLI. La extensión incluye un servidor subyacente de Protocolo de contexto del modelo (MCP), que actúa como intermediario entre Gemini CLI y Knowledge Catalog, lo que elimina la necesidad de una configuración de servidor independiente.

Como alternativa, puedes conectar otros IDEs y herramientas para desarrolladores que admitan MCP con una caja de herramientas de MCP local 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 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:

• Gemini CLI (a través de la extensión)
• Gemini Code Assist
• Claude Code
• Claude para computadoras de escritorio
• Cline (extensión de VS Code)
• Cursor
• Visual Studio Code (Copilot)
• Windsurf (anteriormente Codeium)

Acerca de Gemini CLI y las extensiones

Gemini CLI 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 populares de código abierto.

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

Cómo funcionan las extensiones

Las extensiones amplían las capacidades de Gemini CLI, lo que le permite conectarse a servicios específicos Google Cloud y otras herramientas, y controlarlos. Proporcionan a Gemini contexto y comprensión de la API, lo que permite la interacción conversacional. Puedes cargar extensiones de Gemini CLI desde URLs de GitHub, directorios locales o registros. Estas extensiones ofrecen nuevas herramientas, comandos de barra y mensajes. Estos son independientes de las extensiones de IDE, como Gemini Code Assist, que se integran con MCP Toolbox.

Acerca de la extensión de Knowledge Catalog

La extensión de Knowledge Catalog para Gemini CLI integra la IA en tus tareas de descubrimiento y administración de datos. Puedes interactuar con Knowledge Catalog usando instrucciones en lenguaje natural en tu terminal. Estos son algunos ejemplos:

Categoría	Herramienta	Ejemplo de instrucción en lenguaje natural
Descubrimiento y administración de datos	search_entries	Encuentra todos los conjuntos de datos relacionados con las ventas en Europa. Muéstrame las tablas que contienen PII del cliente. Enumera todos los conjuntos de datos de BigQuery en el lago marketing en Knowledge Catalog.
	lookup_entry	¿Cuál es el esquema de la tabla orders? Describe las reglas de calidad de los datos aplicadas a la base de datos customer. ¿Quién aparece como propietario de la empresa para la tabla customer_details?
	search_aspect_types	Muéstrame los tipos de aspectos relacionados con las reglas de calidad de los datos. Enumera todos los tipos de aspectos que se usan para la administración de datos. ¿Hay algún tipo de aspecto para marcar datos de PII?
Conexión del LLM con el contexto	lookup_context (preview)	Describe el recurso de datos orders. Escribe una consulta en SQL que cuente la cantidad de usuarios por país. Escribe una canalización de datos que limpie la tabla products.

Para obtener más información sobre la extensión de Knowledge Catalog, consulta la Extensión de Gemini CLI: Knowledge Catalog.

Roles obligatorios

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

• Para habilitar las APIs: Administrador Service Usage (roles/serviceusage.serviceUsageAdmin)
• Para usar las herramientas de Knowledge Catalog: Visualizador de catálogo de Dataplex (roles/dataplex.catalogViewer)

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 la extensión de Gemini CLI. 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 la extensión de Gemini CLI:

• Para habilitar las APIs: serviceusage.services.enable
• Para usar las herramientas de Knowledge Catalog:
  • dataplex.projects.search
  • dataplex.entries.get
  • dataplex.aspectTypes.get
  • dataplex.aspectTypes.list

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

Habilitar la API de Dataplex

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

   Ir al selector de proyectos

2. Selecciona o crea un Google Cloud proyecto de.

   Roles necesarios para seleccionar o crear un proyecto

   • Seleccionar 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.
   • Crear un proyecto: Para crear un proyecto, necesitas el rol de creador de proyectos (roles/resourcemanager.projectCreator), que contiene el resourcemanager.projects.create permiso. Obtén más información para otorgar roles.
   Nota: Si no planeas conservar los recursos creados durante este procedimiento, crea un proyecto en lugar de seleccionar un proyecto existente. Cuando termines, puedes borrar el proyecto y quitar todos los recursos asociados con él.

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

4. Habilitar la API de Dataplex

   Roles necesarios para habilitar las APIs

   Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles.

   Habilitar la API

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

   gcloud auth application-default login

   No es necesario que hagas esto si usas Cloud Shell.

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

Instala MCP Toolbox

No es necesario que instales MCP Toolbox si solo planeas usar Gemini Code Assist o la extensión de Gemini CLI, ya que incluyen las capacidades del 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 el objeto binario que corresponde a tu sistema operativo (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.

Si usas Gemini Code Assist o Gemini CLI independiente, no necesitas instalar ni configurar MCP Toolbox, ya que estas herramientas incluyen las capacidades del servidor requeridas. Para obtener instrucciones de configuración, consulta las pestañas Gemini Code Assist o Extensión de Gemini CLI.

Para otras herramientas y otros IDEs compatibles con MCP, primero debes instalar MCP Toolbox. La caja de herramientas actúa como un servidor de Protocolo de contexto del modelo (MCP) 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, selecciona la pestaña de tu herramienta específica para ver las instrucciones de configuración.

Extensión de Gemini CLI

Este método usa la extensión knowledge-catalog dedicada para la herramienta Gemini CLI independiente y no usa MCP Toolbox.

1. Instala el Gemini CLI.
2. Instala la extensión de Knowledge Catalog para Gemini CLI desde el repositorio de GitHub:

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

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

   export DATAPLEX_PROJECT="PROJECT_ID"

   Reemplaza PROJECT_ID por el ID del Google Cloud proyecto.

4. Inicia Gemini CLI en modo interactivo:

   gemini

   La CLI carga automáticamente la extensión de Knowledge Catalog y sus herramientas, que puedes usar para interactuar con tus recursos de datos.

Gemini Code Assist

Gemini Code Assist incluye las capacidades del servidor de MCP requeridas, por lo que no necesitas instalar MCP Toolbox por separado.

1. En VS Code, instala la extensión de Gemini Code Assist.
2. Habilita el modo de agente en el chat de Gemini Code Assist.
3. En tu directorio de trabajo, crea una carpeta llamada .gemini. Dentro de ella, crea un archivo settings.json.
4. Agrega la siguiente configuración, reemplaza las variables de entorno por tus valores y guarda:

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

Claude Code

1. Instala Claude Code.
2. Crea el archivo .mcp.json en la raíz de tu proyecto, si no existe.
3. Agrega la configuración, reemplaza las variables de entorno por tus valores y guarda:

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

Claude para computadoras de escritorio

1. Abre Claude para computadoras de escritorio y navega a Configuración.
2. Para abrir el archivo de configuración, en la pestaña Desarrollador, haz clic en Editar configuración.
3. Agrega la configuración, reemplaza las variables de entorno por tus valores, y guarda:

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

4. Reinicia Claude para computadoras de escritorio.
   En la nueva pantalla de chat, se muestra un ícono de MCP con el nuevo servidor de MCP.

Cline

1. En VS Code, abre la extensión de Cline y, luego, haz clic en el ícono de servidores de MCP.
2. Para abrir el archivo de configuración, presiona Configurar servidores de MCP.
3. Agrega la siguiente configuración, reemplaza las variables de entorno por tus valores y guarda:

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

   Aparecerá un estado activo verde después de que el servidor se conecte correctamente.

Cursor

1. Crea el directorio .cursor en la raíz de tu proyecto si no existe.
2. Crea el archivo .cursor/mcp.json si no existe y ábrelo.
3. Agrega la siguiente configuración, reemplaza las variables de entorno por tus valores y guarda:

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

4. Abre Cursor y navega a Configuración > Configuración del cursor > MCP. Aparecerá un estado activo verde cuando el servidor se conecte.

VS Code (Copilot)

1. Abre VS Code y crea el directorio .vscode en la raíz de tu proyecto si no existe.
2. Crea el archivo .vscode/mcp.json si no existe y ábrelo.
3. Agrega la siguiente configuración, reemplaza las variables de entorno por tus valores y guarda:

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

Windsurf

1. Abre Windsurf y navega al asistente de Cascade.
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, reemplaza las variables de entorno por tus valores y guarda:

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

Usa las herramientas

Tu herramienta de IA ahora está conectada a Knowledge Catalog. Intenta pedirle a tu asistente de IA que encuentre algunos recursos de datos, como conjuntos de datos de BigQuery, instancias de Cloud SQL y otros.

Las siguientes herramientas están disponibles para el LLM:

• search_entries: Busca recursos de datos.
• lookup_entry: Recupera metadatos (por ejemplo, esquema, uso, información general de la empresa y contactos) de los recursos de datos.
• search_aspect_types: Busca tipos de aspectos.
• lookup_context (vista previa): Recupera un conjunto enriquecido de metadatos con formato previo sobre uno o más recursos de datos.

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 según la instrucción del sistema recomendada.

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

• Cuando se te solicite encontrar conjuntos de datos o tablas, usa la herramienta 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 herramienta lookup_entry.
• Cuando se te pregunte sobre las reglas o clasificaciones de administración, comienza usando search_aspect_types para encontrar tipos de aspectos relevantes.
• Si responder preguntas requiere un conjunto amplio de metadatos, usa la herramienta lookup_context para recuperarlos.

Nota: Te recomendamos este paso opcional para obtener una mejor experiencia y evitar trabajo adicional, por ejemplo, diseñar tu propio agente.

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

¿Qué sigue?

• Busca recursos en Knowledge Catalog.
• Obtén información para transferir fuentes personalizadas a Knowledge Catalog.
• Obtén información para administrar aspectos y enriquecer metadatos.
• Consulta el caso de uso Cómo usar el agente de Gemini CLI para obtener contexto de datos.