Associe o seu IDE ao AlloyDB através da MCP Toolbox

Esta página mostra como usar a caixa de ferramentas da MCP para bases de dados para ligar a sua instância do AlloyDB para PostgreSQL a ambientes de desenvolvimento integrados (IDEs) e ferramentas para programadores que suportam o protocolo de contexto do modelo (MCP). Use estas ferramentas para executar consultas SQL e interagir com a sua base de dados. Este guia destina-se a programadores que usam os respetivos IDEs e ferramentas para programadores existentes para trabalhar com o AlloyDB.

Esta página pressupõe que tem uma base de dados do AlloyDB e que a sua instância do AlloyDB tem um endereço IP público. Para mais informações, consulte o artigo Crie uma base de dados do AlloyDB com a caixa de ferramentas do MCP.

O protocolo Model Context Protocol (MCP) é um protocolo aberto para ligar grandes modelos de linguagem (GMLs) a origens de dados, como o AlloyDB. Esta página descreve como usar a caixa de ferramentas do MCP para bases de dados para expor as suas ferramentas de assistência para programadores a uma instância do AlloyDB através do seguinte IDE:

• Cursor
• Windsurf (Codium)
• Visual Studio Code (Copilot)
• Cline (extensão do VS Code)
• Claude para computador
• Código Claude
• CLI do Gemini
• Gemini Code Assist

Antes de começar

Certifique-se de que tem as funções necessárias.

Funções necessárias

Para se ligar à instância do AlloyDB, precisa das seguintes funções ou autorizações de gestão de identidade e acesso (IAM) equivalentes:

• Cliente do AlloyDB na nuvem (roles/alloydb.client)
• Consumidor de utilização de serviços (roles/serviceusage.serviceUsageConsumer)

Configure a base de dados

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

2. Verify that billing is enabled for your Google Cloud project.

3. Ative as APIs Cloud necessárias para criar e estabelecer ligação ao AlloyDB para PostgreSQL.

   Ative as APIs

   1. No passo Confirmar projeto, clique em Seguinte para confirmar o nome do projeto ao qual vai fazer alterações.

   2. No passo Ativar APIs, clique em Ativar para ativar o seguinte:

      • API AlloyDB
      • API Compute Engine
      • Cloud Resource Manager API
      • API de rede de serviços

      A API Service Networking é necessária se planear configurar a conetividade de rede ao AlloyDB através de uma rede VPC que resida no mesmo Google Cloud projeto que o AlloyDB.

      A API Compute Engine e a API Cloud Resource Manager são necessárias se planear configurar a conetividade de rede ao AlloyDB através de uma rede VPC que reside num projeto Google Cloud diferente.

4. Crie ou selecione um cluster e a respetiva instância principal. A caixa de ferramentas do MCP liga-se de forma segura à sua instância através dos conetores de linguagem do AlloyDB.
5. Configure as Credenciais padrão da aplicação (ADC) para o seu ambiente.
6. Crie ou reutilize um utilizador da base de dados. Tenha o nome de utilizador e a palavra-passe prontos para introduzir.

Instale a caixa de ferramentas do MCP

1. Transfira a versão mais recente da MCP Toolbox como um ficheiro binário. Selecione o binário correspondente ao seu sistema operativo (SO) e arquitetura da CPU. Tem de usar a versão V0.7.0 ou posterior da caixa de ferramentas do MCP.

   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. Tornar o ficheiro binário executável.

   chmod +x toolbox
   

3. Valide a instalação.

   ./toolbox --version
   

Configure o cliente do MCP

Código do Claude

1. Instale o Claude Code.
2. Crie o ficheiro .mcp.json na raiz do projeto, se não existir.
3. Adicione a configuração, substitua as variáveis de ambiente pelos seus valores e guarde.




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

1. Abra o Claude Desktop e navegue para Definições.
2. No separador Programador, clique em Editar configuração para abrir o ficheiro de configuração.
3. Adicione a configuração, substitua as variáveis de ambiente pelos seus valores e guarde.




{
  "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. Reinicie o Claude Desktop.
5. O novo ecrã de chat apresenta um ícone de martelo (MCP) com o novo servidor MCP.

Cline

1. Abra a extensão Cline no VS Code e toque no ícone Servidores MCP.
2. Clique em Configurar servidores MCP para abrir o ficheiro de configuração.
3. Adicione a seguinte configuração, substitua as variáveis de ambiente pelos seus valores e guarde.




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


É apresentado um estado ativo verde depois de o servidor se ligar com êxito.



Cursor

1. Crie o diretório .cursor na raiz do projeto, se não existir.
2. Crie o ficheiro .cursor/mcp.json, se não existir, e abra-o.
3. Adicione a seguinte configuração, substitua as variáveis de ambiente pelos seus valores e guarde.

{
  "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. Abra o Cursor e navegue para Definições > Definições do cursor > MCP. É apresentado um estado ativo verde quando o servidor se liga.

Visual Studio Code (Copilot)

1. Abra o VS Code e crie o diretório .vscode na raiz do projeto, se não existir.
2. Crie o ficheiro .vscode/mcp.json, se não existir, e abra-o.
3. Adicione a seguinte configuração, substitua as variáveis de ambiente pelos seus valores e guarde.

{
  "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. Abra o Windsurf e navegue para o assistente Cascade.
2. Clique no ícone do MCP e, de seguida, em Configurar para abrir o ficheiro de configuração.
3. Adicione a seguinte configuração, substitua as variáveis de ambiente pelos seus valores e guarde.

{
  "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 do Gemini

1. Instale a CLI do Gemini.
2. No seu diretório de trabalho, crie uma pasta denominada .gemini. No interior, crie um ficheiro settings.json.
3. Adicione a seguinte configuração, substitua as variáveis de ambiente pelos seus valores e, de seguida, guarde.

{
  "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. Instale a extensão Gemini Code Assist no Visual Studio Code.
2. Ative o modo de agente no chat do Gemini Code Assist.
3. No seu diretório de trabalho, crie uma pasta denominada .gemini. No interior, crie um ficheiro settings.json.
4. Adicione a seguinte configuração, substitua as variáveis de ambiente pelos seus valores e, de seguida, guarde.

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

Use ferramentas de IA

A sua ferramenta de IA está agora ligada ao AlloyDB através do MCP. Experimente pedir ao seu assistente de IA para listar tabelas, criar uma tabela ou definir e executar outras declarações SQL.

As seguintes ferramentas estão disponíveis para o MDG:

• list_tables: apresenta tabelas e descrições.
• execute_sql: executa qualquer declaração SQL.
Nota: as ferramentas pré-criadas são anteriores à versão 1.0, pelo que deve esperar algumas alterações às ferramentas entre as versões. Os MDIs adaptam-se às ferramentas disponíveis, pelo que isto não afeta a maioria dos utilizadores.