Connettere l'IDE ad AlloyDB utilizzando MCP Toolbox

Questa pagina mostra come utilizzare MCP Toolbox for Databases per connettere l'istanza AlloyDB per PostgreSQL a ambienti di sviluppo integrati (IDE) e strumenti per sviluppatori che supportano il Model Context Protocol (MCP). Utilizza questi strumenti per eseguire query SQL e interagire con il database. Questa guida è rivolta agli sviluppatori che utilizzano gli IDE e gli strumenti per sviluppatori esistenti per lavorare con AlloyDB.

Questa pagina presuppone che tu disponga di un database AlloyDB e che la tua istanza AlloyDB abbia un indirizzo IP pubblico. Per saperne di più, consulta Creare un database AlloyDB con MCP Toolbox.

Il Model Context Protocol (MCP) è un protocollo aperto per connettere modelli linguistici di grandi dimensioni (LLM) a origini dati come AlloyDB. Questa pagina descrive come utilizzare MCP Toolbox for Databases per esporre gli strumenti di assistenza per sviluppatori a un'istanza AlloyDB utilizzando il seguente IDE:

• Cursore
• Windsurf (Codium)
• Visual Studio Code (Copilot)
• Cline (estensione VS Code)
• Claude desktop
• Claude code
• Interfaccia a riga di comando di Gemini
• Gemini Code Assist

Prima di iniziare

Assicurati di disporre dei ruoli richiesti.

Ruoli obbligatori

Per connetterti all'istanza AlloyDB, devi disporre dei seguenti ruoli o autorizzazioni IAM (Identity and Access Management) equivalenti:

• Cloud AlloyDB Client (roles/alloydb.client)
• Consumer utilizzo dei servizi (roles/serviceusage.serviceUsageConsumer)

Configurare il database

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. Abilita le API Cloud necessarie per creare e connetterti ad AlloyDB per PostgreSQL.

   Abilita le API

   1. Nel passaggio Conferma progetto, fai clic su Avanti per confermare il nome del progetto a cui apporterai le modifiche.

   2. Nel passaggio Abilita API, fai clic su Abilita per abilitare quanto segue:

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

      L'API Service Networking è necessaria se prevedi di configurare la connettività di rete ad AlloyDB utilizzando una rete VPC che si trova nello stesso Google Cloud progetto di AlloyDB.

      L'API Compute Engine e l'API Cloud Resource Manager sono necessarie se prevedi di configurare la connettività di rete ad AlloyDB utilizzando una rete VPC che si trova in un progetto Google Cloud diverso.

2. Crea o seleziona un cluster e la relativa istanza principale. MCP Toolbox si connette in modo sicuro alla tua istanza utilizzando i connettori dei linguaggi AlloyDB.
3. Configura le credenziali predefinite dell'applicazione (ADC) per il tuo ambiente.
4. Crea o riutilizza un utente del database. Tieni a portata di mano nome utente e password.

Installare MCP Toolbox

1. Scarica l'ultima versione di MCP Toolbox come file binario. Seleziona il file binario corrispondente al tuo sistema operativo e all'architettura della CPU. Devi utilizzare MCP Toolbox versione V0.7.0 o successive.

   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. Rendi il binario un eseguibile.

   chmod +x toolbox
   

3. Verifica l'installazione.

   ./toolbox --version
   

Configura il client MCP

Codice Claude

1. Installa Claude Code.
2. Crea il file .mcp.json nella root del progetto, se non esiste.
3. Aggiungi la configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva.




{
  "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 desktop

1. Apri Claude Desktop e vai a Impostazioni.
2. Nella scheda Sviluppatore, fai clic su Modifica configurazione per aprire il file di configurazione.
3. Aggiungi la configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva.




{
  "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. Riavvia Claude Desktop.
5. Nella nuova schermata della chat viene visualizzata un'icona a forma di martello (MCP) con il nuovo server MCP.

Cline

1. Apri l'estensione Cline in VS Code e tocca l'icona Server MCP.
2. Fai clic su Configura server MCP per aprire il file di configurazione.
3. Aggiungi la seguente configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva.




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


Dopo la connessione riuscita del server, viene visualizzato uno stato attivo verde.



Cursore

1. Crea la directory .cursor nella root del progetto, se non esiste.
2. Crea il file .cursor/mcp.json se non esiste e aprilo.
3. Aggiungi la seguente configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva.

{
  "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. Apri Cursore e vai a Impostazioni > Impostazioni cursore > MCP. Quando il server si connette, viene visualizzato uno stato attivo verde.

Visual Studio Code (Copilot)

1. Apri VS Code e crea la directory .vscode nella radice del progetto, se non esiste.
2. Crea il file .vscode/mcp.json se non esiste e aprilo.
3. Aggiungi la seguente configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva.

{
  "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. Apri Windsurf e vai all'assistente per le cascate.
2. Fai clic sull'icona di MCP, quindi su Configura per aprire il file di configurazione.
3. Aggiungi la seguente configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva.

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

Interfaccia a riga di comando di Gemini

1. Installa l'interfaccia a riga di comando di Gemini.
2. Nella directory di lavoro, crea una cartella denominata .gemini. Al suo interno, crea un file settings.json.
3. Aggiungi la seguente configurazione, sostituisci le variabili di ambiente con i tuoi valori e poi salva.

{
  "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. Installa l'estensione Gemini Code Assist in Visual Studio Code.
2. Attiva la modalità Agente nella chat di Gemini Code Assist.
3. Nella directory di lavoro, crea una cartella denominata .gemini. Al suo interno, crea un file settings.json.
4. Aggiungi la seguente configurazione, sostituisci le variabili di ambiente con i tuoi valori e poi salva.

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

Utilizzare gli strumenti di AI

Il tuo strumento di AI è ora connesso ad AlloyDB tramite MCP. Prova a chiedere all'assistente AI di elencare le tabelle, crearne una o definire ed eseguire altre istruzioni SQL.

Sono disponibili i seguenti strumenti per il LLM:

• list_tables: elenca tabelle e descrizioni.
• execute_sql: esegue qualsiasi istruzione SQL.
Nota: gli strumenti predefiniti sono precedenti alla versione 1.0, quindi prevedi alcune modifiche agli strumenti tra le versioni. I LLM si adattano agli strumenti disponibili, quindi questa modifica non influisce sulla maggior parte degli utenti.