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. 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 Gemini CLI, 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 para bases de datos. 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 el agrupamiento 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 Kubernetes 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 ayuda con la codificació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 populares de código abierto.

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 Gemini CLI con instrucciones en 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 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 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 hay disponibles?
list_schemas Enumera todos los esquemas.
list_triggers Muéstrame los activadores de 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
  • Integrada en tu IDE con Gemini Code Assist

Gemini CLI

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

  1. Instala y configura Gemini CLI y la postgres extensión como se describe en la pestaña Gemini CLI.
  2. Configura Gemini Code Assist para que use Gemini CLI.
  3. Comienza a interactuar con tu instancia de AlloyDB Omni con 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 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 tu herramienta de agente entre las siguientes opciones:

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": {
    "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. Aparecerá un estado activo verde cuando se conecte el servidor.

Windsurf

  1. Abre Windsurf y navega al asistente de 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.
{
  "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 de Cline en VS Code y haz clic en el ícono MCP Servers.
  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"
      }
    }
  }
}
  1. Aparecerá un estado activo verde después de que el servidor se conecte correctamente.

Claude para computadoras de escritorio

  1. Abre Claude para computadoras de escritorio y navega a Settings.
  2. En la pestaña Developer, haz clic en Edit Config para abrir el archivo de configuración.
  3. Agrega la 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"
      }
    }
  }
}
  1. Reinicia Claude para computadoras de escritorio.
  2. En la nueva pantalla de chat, se 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 de tu proyecto si no existe.
  3. Agrega la 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"
      }
    }
  }
}
  1. Reinicia Claude Code para aplicar la nueva configuración.