Usa AlloyDB Omni con MCP, Gemini CLI y otros agentes

En este documento, se describe cómo conectar tu instancia de AlloyDB Omni a varios agentes que admiten el Protocolo de contexto del modelo (MCP).

Dado que AlloyDB Omni es compatible con PostgreSQL, puedes usar herramientas y extensiones diseñadas para PostgreSQL.

Para la configuración más simple, usa la extensión de PostgreSQL dedicada para Gemini CLI. Esta integra el servidor de MCP subyacente directamente en la extensión, por lo que no es necesario que realices una configuración de servidor independiente. Puedes configurar Gemini Code Assist para que use la CLI de Gemini, lo que ofrece beneficios de configuración similares en tu IDE.

Como alternativa, otros IDE y agentes que admiten el MCP pueden conectarse a través de MCP Toolbox for Databases. Toolbox es un servidor de MCP de código abierto diseñado para conectar agentes de IA a tus datos. Maneja tareas como la autenticación y la agrupación de conexiones, lo que te permite interactuar con tus datos en lenguaje natural directamente desde tu IDE.

Antes de comenzar

Antes de conectarte a tu instancia de AlloyDB Omni, asegúrate de hacer lo siguiente:

1. Instala AlloyDB Omni para Kubernetes o AlloyDB Omni para contenedores y ten una instancia de base de datos en ejecución.
2. Crea o reutiliza un usuario de la base de datos. Ten a mano el nombre de usuario y la contraseña.

Usa la extensión de Gemini CLI para PostgreSQL

Nota: La extensión de Gemini CLI para PostgreSQL se basa en MCP Toolbox for Databases. La caja de herramientas de MCP para bases de datos está en versión beta (anterior a la v1.0) y puede tener cambios rotundos hasta la primera versión estable (v1.0).

La CLI de Gemini es un agente de IA de código abierto diseñado para ayudar con los flujos de trabajo de desarrollo, ya que asiste con la programación, la depuración, la exploración de datos y la creación de contenido. Su misión es proporcionar una interfaz de agente para interactuar con los servicios de Data Cloud y las bases de datos de código abierto populares.

La integración con Gemini CLI para AlloyDB Omni se realiza a través de la extensión de PostgreSQL. Esta extensión proporciona un conjunto de herramientas para interactuar con PostgreSQL y AlloyDB Omni, lo que te permite administrar tus bases de datos, ejecutar consultas y explorar esquemas directamente desde la CLI de Gemini con instrucciones de lenguaje natural.

En los siguientes ejemplos, se usa una base de datos ecommerce de muestra con las siguientes tablas:

• products: Contiene información del producto, incluidos product_id, product_name, category y price.
• customers: Almacena datos del cliente, como customer_id, first_name, last_name y email.
• orders: Contiene información del pedido, incluidos order_id, customer_id y order_date.

Las siguientes herramientas están disponibles en la extensión de PostgreSQL:

Categoría	Herramienta	Ejemplo de instrucción en lenguaje natural
Operaciones de bases de datos	execute_sql	Muéstrame los 10 productos más caros de la categoría "Laptops".
	get_query_plan	Explica el plan de ejecución de una consulta que encuentra a todos los clientes que no realizaron un pedido en los últimos 6 meses.
	list_active_queries	¿Qué consultas se ejecutan en la base de datos?
	database_overview	Dame una descripción general de la base de datos actual.
	list_tables	Muéstrame todas las tablas de la base de datos actual.
	list_views	¿Qué vistas están disponibles?
	list_schemas	Enumera todos los esquemas.
	list_triggers	Muéstrame los activadores en la tabla de pedidos.
	list_available_extensions	¿Qué extensiones disponibles puedo instalar?
	list_installed_extensions	Enumera todas las extensiones instaladas.
	list_indexes	Enumera todos los índices.
	list_sequences	Enumera todas las secuencias.
Estado y mantenimiento de la base de datos	list_autovacuum_configurations	Muéstrame la configuración actual de autovacuum.
	list_memory_configurations	¿Cuáles son las configuraciones de memoria actuales?
	list_top_bloated_tables	Enumera las cinco tablas más infladas.
	list_replication_slots	Muestra todos los espacios de replicación activos.
	list_invalid_indexes	Verifica si hay índices no válidos en la base de datos ecommerce.
	long_running_transactions	Muéstrame las transacciones de larga duración.
	list_locks	Enumera todos los bloqueos.
	replication_stats	Muéstrame las estadísticas de replicación.

Puedes usar la extensión de Gemini CLI para PostgreSQL de dos maneras:

• Una herramienta de línea de comandos independiente
• Integrado en tu IDE con Gemini Code Assist

CLI de Gemini

1. Instala la Gemini CLI (versión 0.6.0 o posterior).
2. Instala la extensión de PostgreSQL para Gemini CLI desde el repositorio de GitHub con el siguiente comando:

   gemini extensions install https://github.com/gemini-cli-extensions/postgres

3. Establece variables de entorno para conectarte a tu instancia de AlloyDB Omni:

   export POSTGRES_HOST="DATABASE_HOST"
   export POSTGRES_PORT="DATABASE_PORT"
   export POSTGRES_DATABASE="DATABASE_NAME"
   export POSTGRES_USER="DATABASE_USER"
   export POSTGRES_PASSWORD="DATABASE_PASSWORD"
   

   También puedes cargar estas variables desde un archivo .env en tu directorio de trabajo.

4. Inicia la Gemini CLI en modo interactivo:

   gemini

   La CLI carga automáticamente la extensión de PostgreSQL y sus herramientas, que puedes usar para interactuar con tu base de datos.

Gemini Code Assist

Para evitar configurar un servidor de MCP de forma manual, configura Gemini Code Assist para que use la CLI de Gemini.

1. Instala y configura la Gemini CLI y la extensión de postgres como se describe en la pestaña Gemini CLI.
2. Configura Gemini Code Assist para usar la CLI de Gemini.
3. Comienza a interactuar con tu instancia de AlloyDB Omni usando lenguaje natural directamente en el chat de Gemini Code Assist.

Conéctate con otros IDEs usando MCP Toolbox para bases de datos

En esta sección, se describe cómo conectarse a tu instancia de AlloyDB Omni desde varios agentes con MCP Toolbox for Databases.

Instala MCP Toolbox para bases de datos

Para conectar tu IDE a AlloyDB Omni, debes instalar MCP Toolbox for Databases, un servidor de código abierto que conecta agentes de IA a tus datos.

1. Descarga la versión más reciente de Toolbox como un archivo binario. Selecciona el objeto binario correspondiente a tu sistema operativo (SO) y a la arquitectura de CPU.

   linux/amd64

   curl -L -O https://storage.googleapis.com/genai-toolbox/v0.21.0/linux/amd64/toolbox

   darwin/arm64

   curl -L -O https://storage.googleapis.com/genai-toolbox/v0.21.0/darwin/arm64/toolbox

   darwin/amd64

   curl -L -O https://storage.googleapis.com/genai-toolbox/v0.21.0/darwin/amd64/toolbox

   windows/amd64

   curl -L -O https://storage.googleapis.com/genai-toolbox/v0.21.0/windows/amd64/toolbox.exe

2. Haz que el objeto binario sea ejecutable.

   chmod +x toolbox
   

3. Verifica la instalación:.

   ./toolbox --version
   

Configura tu cliente

Selecciona la herramienta del agente entre las siguientes opciones:

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, reemplaza las variables de entorno por tus valores y guarda.

{
  "mcpServers": {
    "alloydbomni": {
      "command": "PATH_TO_TOOLBOX",
      "args": ["--prebuilt","postgres","--stdio"],
      "env": {
        "POSTGRES_HOST": "DATABASE_HOST",
        "POSTGRES_PORT": "DATABASE_PORT",
        "POSTGRES_DATABASE": "DATABASE_NAME",
        "POSTGRES_USER": "DATABASE_USER",
        "POSTGRES_PASSWORD": "DATABASE_PASSWORD"
      }
    }
  }
}

4. Abre Cursor y navega a Configuración > Configuración del cursor > MCP. Cuando el servidor se conecta, aparece un estado activo de color verde.

Windsurf

1. Abre Windsurf y navega al asistente de Cascade.
2. Haz clic en el ícono de MCP y, luego, en Configurar para abrir el archivo de configuración.
3. Agrega la siguiente configuración, reemplaza las variables de entorno por tus valores y guarda.

{
  "mcpServers": {
    "alloydbomni": {
      "command": "PATH_TO_TOOLBOX",
      "args": ["--prebuilt","postgres","--stdio"],
      "env": {
        "POSTGRES_HOST": "DATABASE_HOST",
        "POSTGRES_PORT": "DATABASE_PORT",
        "POSTGRES_DATABASE": "DATABASE_NAME",
        "POSTGRES_USER": "DATABASE_USER",
        "POSTGRES_PASSWORD": "DATABASE_PASSWORD"
      }
    }
  }
}

Visual Studio 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": {
    "alloydbomni": {
      "command": "PATH_TO_TOOLBOX",
      "args": ["--prebuilt","postgres","--stdio"],
      "env": {
        "POSTGRES_HOST": "DATABASE_HOST",
        "POSTGRES_PORT": "DATABASE_PORT",
        "POSTGRES_DATABASE": "DATABASE_NAME",
        "POSTGRES_USER": "DATABASE_USER",
        "POSTGRES_PASSWORD": "DATABASE_PASSWORD"
      }
    }
  }
}

Cline

1. Abre la extensión Cline en VS Code y haz clic en el ícono de Servidores de MCP.
2. Haz clic en Configure MCP Servers para abrir el archivo de configuración.
3. Agrega la siguiente configuración, reemplaza las variables de entorno por tus valores y guarda.

{
  "mcpServers": {
    "alloydbomni": {
      "command": "PATH_TO_TOOLBOX",
      "args": ["--prebuilt","postgres","--stdio"],
      "env": {
        "POSTGRES_HOST": "DATABASE_HOST",
        "POSTGRES_PORT": "DATABASE_PORT",
        "POSTGRES_DATABASE": "DATABASE_NAME",
        "POSTGRES_USER": "DATABASE_USER",
        "POSTGRES_PASSWORD": "DATABASE_PASSWORD"
      }
    }
  }
}
      

4. Aparece un estado activo de color verde después de que el servidor se conecta correctamente.

Claude para computadoras de escritorio

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

{
  "mcpServers": {
    "alloydbomni": {
      "command": "PATH_TO_TOOLBOX",
      "args": ["--prebuilt","postgres","--stdio"],
      "env": {
        "POSTGRES_HOST": "DATABASE_HOST",
        "POSTGRES_PORT": "DATABASE_PORT",
        "POSTGRES_DATABASE": "DATABASE_NAME",
        "POSTGRES_USER": "DATABASE_USER",
        "POSTGRES_PASSWORD": "DATABASE_PASSWORD"
      }
    }
  }
}

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

Código de Claude

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 los cambios.

{
  "mcpServers": {
    "alloydbomni": {
      "command": "PATH_TO_TOOLBOX",
      "args": ["--prebuilt","postgres","--stdio"],
      "env": {
        "POSTGRES_HOST": "DATABASE_HOST",
        "POSTGRES_PORT": "DATABASE_PORT",
        "POSTGRES_DATABASE": "DATABASE_NAME",
        "POSTGRES_USER": "DATABASE_USER",
        "POSTGRES_PASSWORD": "DATABASE_PASSWORD"
      }
    }
  }
}

4. Reinicia el código de Claude para aplicar la nueva configuración.