Conecta tu IDE a AlloyDB con MCP Toolbox

En esta página, se muestra cómo usar la caja de herramientas de MCP para bases de datos para conectar tu instancia de AlloyDB para PostgreSQL a entornos de desarrollo integrados (IDE) y herramientas para desarrolladores que admiten el Protocolo de contexto del modelo (MCP). Usa estas herramientas para ejecutar consultas en SQL e interactuar con tu base de datos. Esta guía está dirigida a los desarrolladores que usan sus IDE y herramientas para desarrolladores existentes para trabajar con AlloyDB.

En esta página, se supone que tienes una base de datos de AlloyDB y que tu instancia de AlloyDB tiene una dirección IP pública. Para obtener más información, consulta Crea una base de datos de AlloyDB con MCP Toolbox.

El Protocolo de contexto del modelo (MCP) es un protocolo abierto para conectar modelos de lenguaje grandes (LLM) a fuentes de datos, como AlloyDB. En esta página, se describe cómo usar MCP Toolbox for Databases para exponer tus herramientas de asistencia para desarrolladores a una instancia de AlloyDB con el siguiente IDE:

• Cursor
• Windsurf (Codium)
• Visual Studio Code (Copilot)
• Cline (extensión de VS Code)
• Claude para computadoras
• Claude code
• CLI de Gemini
• Gemini Code Assist

Antes de comenzar

Asegúrate de tener los roles necesarios.

Roles requeridos

Para conectarte a la instancia de AlloyDB, necesitas los siguientes roles o permisos equivalentes de Identity and Access Management (IAM):

• Cliente de Cloud AlloyDB (roles/alloydb.client)
• Consumidor de Service Usage (roles/serviceusage.serviceUsageConsumer)

Configura la 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.

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.

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 y conectarte a AlloyDB para PostgreSQL.

   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. MCP Toolbox se conecta de forma segura a tu instancia con los conectores de lenguaje de AlloyDB.
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.

Instala MCP Toolbox

1. Descarga la versión más reciente de MCP 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.7.0 o posterior de MCP Toolbox.

   linux/amd64

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

   darwin/arm64

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

   darwin/amd64

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

   windows/amd64

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

2. Haz que el objeto binario sea ejecutable.

   chmod +x toolbox
   

3. Verifica la instalación:.

   ./toolbox --version
   

Configura el cliente de MCP

Código de Claude

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": {
    "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"
      }
    }
  }
}

Claude para computadoras

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"
      }
    }
  }
}

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.

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 de color verde después de que el servidor se conecta correctamente.



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"
      }
    }
  } 
}

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"
      }
    }
  }
}

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"
      }
    }
  }
}

CLI de Gemini

1. Instala la CLI de Gemini.
2. En tu directorio de trabajo, crea una carpeta llamada .gemini. Dentro de él, crea un archivo settings.json.
3. Agrega la siguiente configuración, reemplaza las variables de entorno por tus valores y, luego, 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"
      }
    }
  }
}

Gemini Code Assist

1. Instala la extensión de Gemini Code Assist en Visual Studio Code.
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 él, crea un archivo settings.json.
4. Agrega la siguiente configuración, reemplaza las variables de entorno por tus valores y, luego, 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"
      }
    }
  }
}

Usa herramientas de IA

Tu herramienta de IA ahora está conectada a AlloyDB a través de MCP. Intenta pedirle a tu asistente de IA que enumere tablas, cree una tabla o defina y ejecute otras instrucciones de SQL.

Las siguientes herramientas están disponibles para el LLM:

• list_tables: Enumera las tablas y las descripciones.
• execute_sql: Ejecuta cualquier instrucción de SQL.
Nota: Las herramientas prediseñadas son anteriores a la versión 1.0, por lo que se esperan algunos cambios entre versiones. Los LLM se adaptan a las herramientas disponibles, por lo que esto no afecta a la mayoría de los usuarios.