Usa AlloyDB Omni con MCP, Gemini CLI y otros agentes

Selecciona una versión de la documentación:

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

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

Para la configuración más sencilla, usa la extensión de PostgreSQL dedicada para Gemini CLI, que integra el servidor de MCP subyacente directamente en la extensión, por lo que no necesitas realizar 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 IDEs y agentes que admiten el MCP pueden conectarse a través de MCP Toolbox para bases de datos. Toolbox es un servidor de MCP de código abierto diseñado para conectar agentes de IA a tus datos. Se encarga de tareas como la autenticación y la agrupación de conexiones, lo que te permite interactuar con tus datos con 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 contenedores y ten una instancia de base de datos en ejecución.
  2. Crea o reutiliza un usuario de base de datos. Prepárate para ingresar el nombre de usuario y la contraseña.

Usa la extensión de Gemini CLI para PostgreSQL

Gemini CLI 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 agentes para interactuar con los servicios de Data Cloud y las bases de datos de código abierto populares.

La integración con la CLI de Gemini 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 de clientes, 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 de 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 consulta para una consulta que encuentre a todos los clientes que no hayan realizado 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 de la tabla de pedidos.
list_available_extensions ¿Cuáles son las extensiones disponibles que puedo instalar?
list_installed_extensions Enumera todas las extensiones que están 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 todas las ranuras de replicación activas.
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

Gemini CLI

  1. Instala la CLI de Gemini (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 CLI de Gemini 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 manualmente un servidor de MCP, configura Gemini Code Assist para que use Gemini CLI.

  1. Instala y configura la Gemini CLI y la extensión de postgres como se describe en la pestaña de la Gemini CLI.
  2. Configura Gemini Code Assist para usar Gemini CLI.
  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 para bases de datos.

Instala MCP Toolbox para bases de datos

Para conectar tu IDE a AlloyDB Omni, debes instalar MCP Toolbox para bases de datos, 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 objeto binario. Selecciona el objeto binario correspondiente a tu sistema operativo (SO) y arquitectura de la 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 de 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 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"
      }
    }
  }
}
  1. Abre Cursor y navega a Settings > Cursor Settings > MCP. Cuando el servidor se conecta, aparece un estado activo de color verde.

Windsurf

  1. Abre Windsurf y navega al asistente Cascade.
  2. Haz clic en el ícono de MCP y, luego, en Configure para abrir el archivo de configuración.
  3. Agrega la siguiente 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"
      }
    }
  }
}

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 los cambios.
{
  "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 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"
      }
    }
  }
}
  1. Aparecerá un estado activo de color verde después de que el servidor se conecte 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"
      }
    }
  }
}
  1. Reinicia Claude para computadoras de escritorio.
  2. La nueva pantalla de chat muestra un ícono de martillo (MCP) con el nuevo servidor de MCP.

Claude Code

  1. Instala Claude Code.
  2. Crea el archivo .mcp.json en la raíz del 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"
      }
    }
  }
}
  1. Reinicia Claude Code para aplicar la configuración nueva.