Usa AlloyDB para PostgreSQL con MCP, la CLI de Gemini y otros agentes

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

Te recomendamos que uses la extensión de AlloyDB dedicada para Gemini CLI. La CLI de Gemini 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.

También se pueden conectar otros IDE y agentes que admitan el MCP 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

Para conectarte a tu instancia de AlloyDB y usar las herramientas disponibles, debes tener uno de los siguientes roles de Identity and Access Management (IAM) o un rol personalizado con permisos equivalentes:

Tarea	Nombre del rol	Rol de Identity and Access Management (IAM) requerido
Usa herramientas de solo lectura para enumerar y obtener recursos de AlloyDB	Visualizador de AlloyDB	roles/alloydb.viewer
Conéctate a una instancia y ejecuta consultas	Cliente de Cloud AlloyDB	roles/alloydb.client
	Consumidor de Service Usage	roles/serviceusage.serviceUsageConsumer
Realizar tareas administrativas (como crear o administrar clústeres, instancias y usuarios)	Administrador de AlloyDB	roles/alloydb.admin
Usa la extensión de observabilidad	Visualizador de Monitoring	roles/monitoring.viewer

Antes de conectarte a tu instancia de AlloyDB, completa los siguientes pasos para configurar tu proyecto y tu base de datos.

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. Habilita las API de Cloud necesarias para crear una conexión a AlloyDB.

   Habilita las APIs

   1. En el paso Confirmar proyecto, haz clic en Siguiente para confirmar el nombre del proyecto en el que realizarás cambios.

   2. En el paso Habilitar APIs, haz clic en Habilitar para habilitar lo siguiente:

      • API de AlloyDB
      • API de Compute Engine
      • API de Cloud Resource Manager
      • API de Service Networking

      La API de Service Networking es obligatoria si planeas configurar la conectividad de red a AlloyDB con una red de VPC que resida en el mismo proyecto Google Cloud que AlloyDB.

      La API de Compute Engine y la API de Cloud Resource Manager son necesarias si planeas configurar la conectividad de red a AlloyDB con una red de VPC que reside en un Google Cloud proyecto diferente.

2. Crea o selecciona un clúster y su instancia principal.
3. Configura las credenciales predeterminadas de la aplicación (ADC) para tu entorno.
4. Crea o reutiliza un usuario de base de datos. Ten a mano el nombre de usuario y la contraseña.

Usa las extensiones de Gemini CLI para AlloyDB

Nota: La extensión de AlloyDB Gemini CLI se basa en MCP Toolbox for Databases. Actualmente, MCP Toolbox for Databases se encuentra en versión beta (anterior a la versión 1.0) y es posible que sufra cambios rotundos hasta el lanzamiento de 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 se realiza a través de extensiones dedicadas que ofrecen capacidades adicionales en comparación con una conexión estándar de MCP Toolbox. En las siguientes secciones, se describen las extensiones alloydb y alloydb-observability, que ofrecen un proceso de instalación y un conjunto de herramientas. Las extensiones de código abierto contienen información detallada sobre la instalación, la configuración y ejemplos de uso. Para obtener más información, consulta la extensión de la CLI de Gemini: AlloyDB para PostgreSQL.

La extensión alloydb incluye herramientas para consultar la base de datos, administrar los recursos de AlloyDB y supervisar el estado de la base de datos.

Categoría	Herramientas	Ejemplo de instrucción en lenguaje natural
Operaciones de bases de datos	list_tables	Muéstrame todas las tablas de la base de datos actual.
	execute_sql	Ejecuta la consulta: SELECT * FROM products WHERE category = 'electronics';
	list_active_queries	¿Qué consultas se ejecutan en la base de datos?
	get_query_plan	Explica el plan de consulta para "SELECT * FROM customers WHERE last_seen > '2025-08-01'".
	list_available_extensions	¿Qué extensiones disponibles puedo instalar?
	list_installed_extensions	Enumera todas las extensiones instaladas.
Administración de recursos clústeres, instancias, usuarios	create_cluster	Crea un clúster de AlloyDB llamado sales-quarterly-db en la región us-east1.
	get_cluster	Obtén los detalles del clúster sales-quarterly-db.
	list_clusters	Enumera todos mis clústeres de AlloyDB.
	create_instance	Crea una instancia de lectura nueva en el clúster sales-quarterly-db.
	get_instance	Muéstrame la información de la instancia sales-quarterly-db-rp.
	list_instances	Enumera todas las instancias del clúster sales-quarterly-db.
	create_user	Crea un usuario de base de datos nuevo llamado reporting_user.
	get_user	Obtiene la información del usuario reporting_user.
	list_users	Enumera todos los usuarios de la base de datos.
	wait_for_operation	¿Cuál es el estado de la operación operation-163562789?
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 los parámetros de configuración de memoria actuales para la instancia principal?
	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 orders.

La extensión alloydb-observability proporciona una interfaz unificada para administrar y supervisar el rendimiento y el estado de la base de datos directamente desde la CLI de Gemini.

Categoría	Herramientas	Ejemplo de instrucción en lenguaje natural
Observabilidad	get_system_metrics	¿Cuáles son las métricas del sistema, como el uso de CPU, de la última hora?
	get_query_metrics	Muéstrame las métricas de rendimiento de las consultas de los últimos 15 minutos.

Puedes usar la extensión de Gemini CLI para AlloyDB 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 CLI de Gemini.
2. Instala la extensión de AlloyDB para Gemini CLI desde el repositorio de GitHub con el siguiente comando:

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

3. Configura las variables de entorno para conectarte a tu instancia de AlloyDB:

   export ALLOYDB_POSTGRES_PROJECT="PROJECT_ID"
   export ALLOYDB_POSTGRES_REGION="REGION"
   export ALLOYDB_POSTGRES_CLUSTER="CLUSTER_NAME"
   export ALLOYDB_POSTGRES_INSTANCE="INSTANCE_NAME"
   export ALLOYDB_POSTGRES_DATABASE="DATABASE_NAME"
   

   De forma predeterminada, la extensión de Gemini CLI para AlloyDB usa tus [credenciales predeterminadas de la aplicación (ADC)](/authentication/application-default-credentials) para la autenticación. Si, en cambio, quieres conectarte como usuario de la base de datos, configura las siguientes variables de entorno opcionales:

   #Optional: Set for database user authentication
   export ALLOYDB_POSTGRES_USER="USERNAME"
   export ALLOYDB_POSTGRES_PASSWORD="PASSWORD"
   

   Para conectarte con una dirección IP privada, también debes configurar la siguiente variable de entorno:

   export ALLOYDB_POSTGRES_IP_TYPE="private"
   

4. Inicia la CLI de Gemini en modo interactivo:

   gemini
   

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

Gemini Code Assist

Te recomendamos que configures Gemini Code Assist para que use la CLI de Gemini. Este enfoque elimina la necesidad de configurar manualmente un servidor de MCP.

1. Asegúrate de haber instalado y configurado la CLI de Gemini y la extensión de alloydb.
2. Configura Gemini Code Assist para usar la CLI de Gemini.
3. Comienza a interactuar con tu instancia de AlloyDB usando lenguaje natural directamente en el chat de Gemini Code Assist.

Conéctate con otros IDEs usando MCP Toolbox for Databases

En esta sección, se describe cómo conectarse a tu instancia de AlloyDB desde varios agentes con MCP Toolbox for Databases. Toolbox actúa como un servidor de Protocolo de contexto del modelo (MCP) de código abierto que se encuentra entre tu IDE y tu base de datos, y proporciona un plano de control para tus herramientas de IA. En esta sección, se proporcionan instrucciones para conectarse a una instancia de AlloyDB con una dirección IP pública o privada. De forma predeterminada, Toolbox usa una dirección IP pública, pero puedes configurar una conexión de IP privada estableciendo la variable de entorno ALLOYDB_POSTGRES_IP_TYPE como se muestra en los ejemplos de configuración.

Instala MCP Toolbox for Databases

Para conectar tu IDE a AlloyDB, 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. Debes usar la versión v0.15.0 o una posterior de Toolbox.

   linux/amd64

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

   darwin/arm64

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

   darwin/amd64

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

   windows/amd64

   curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/windows/amd64/toolbox
   
   

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:

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




{
  "mcpServers": {
    "alloydb": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","alloydb-postgres","--stdio"],
      "env": {
          "ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
          "ALLOYDB_POSTGRES_REGION": "REGION",
          "ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
          "ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
          "ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
          "ALLOYDB_POSTGRES_USER": "USERNAME",
          "ALLOYDB_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}

Nota: Para conectarte con una dirección IP privada, agrega la siguiente línea al objeto env: "ALLOYDB_POSTGRES_IP_TYPE": "private"

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": {
    "alloydb": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","alloydb-postgres","--stdio"],
      "env": {
          "ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
          "ALLOYDB_POSTGRES_REGION": "REGION",
          "ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
          "ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
          "ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
          "ALLOYDB_POSTGRES_USER": "USERNAME",
          "ALLOYDB_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}

Nota: Para conectarte con una dirección IP privada, agrega la siguiente línea al objeto env: "ALLOYDB_POSTGRES_IP_TYPE": "private"

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

Cline

1. Abre la extensión Cline en VS Code y presiona 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": {
    "alloydb": {
     "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","alloydb-postgres","--stdio"],
      "env": {
          "ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
          "ALLOYDB_POSTGRES_REGION": "REGION",
          "ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
          "ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
          "ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
          "ALLOYDB_POSTGRES_USER": "USERNAME",
          "ALLOYDB_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}


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



Nota: Para conectarte con una dirección IP privada, agrega la siguiente línea al objeto env: "ALLOYDB_POSTGRES_IP_TYPE": "private"

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": {
    "alloydb": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","alloydb-postgres","--stdio"],
      "env": {
          "ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
          "ALLOYDB_POSTGRES_REGION": "REGION",
          "ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
          "ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
          "ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
          "ALLOYDB_POSTGRES_USER": "USERNAME",
          "ALLOYDB_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}

Nota: Para conectarte con una dirección IP privada, agrega la siguiente línea al objeto env: "ALLOYDB_POSTGRES_IP_TYPE": "private"

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.

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": {
    "alloydb": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","alloydb-postgres","--stdio"],
      "env": {
        "ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
        "ALLOYDB_POSTGRES_REGION": "REGION",
        "ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
        "ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
        "ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
        "ALLOYDB_POSTGRES_USER": "USERNAME",
        "ALLOYDB_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}

Nota: Para conectarte con una dirección IP privada, agrega la siguiente línea al objeto env: "ALLOYDB_POSTGRES_IP_TYPE": "private"

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": {
    "alloydb": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","alloydb-postgres","--stdio"],
      "env": {
          "ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
          "ALLOYDB_POSTGRES_REGION": "REGION",
          "ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
          "ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
          "ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
          "ALLOYDB_POSTGRES_USER": "USERNAME",
          "ALLOYDB_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}

Nota: Para conectarte con una dirección IP privada, agrega la siguiente línea al objeto env: "ALLOYDB_POSTGRES_IP_TYPE": "private"