Conectar seu ambiente de desenvolvimento integrado ao AlloyDB usando a caixa de ferramentas do MCP

Nesta página, mostramos como usar a caixa de ferramentas do MCP para bancos de dados e conectar sua instância do AlloyDB para PostgreSQL a ambientes de desenvolvimento integrado (IDEs) e ferramentas para desenvolvedores que oferecem suporte ao Protocolo de contexto de modelo (MCP). Use essas ferramentas para executar consultas SQL e interagir com seu banco de dados. Este guia é destinado a desenvolvedores que usam IDEs e ferramentas de desenvolvimento atuais para trabalhar com o AlloyDB.

Esta página pressupõe que você tenha um banco de dados do AlloyDB e que sua instância do AlloyDB tenha um endereço IP público. Para mais informações, consulte Criar um banco de dados do AlloyDB com a caixa de ferramentas do MCP.

O Protocolo de Contexto de Modelo (MCP) é um protocolo aberto para conectar modelos de linguagem grandes (LLMs) a fontes de dados como o AlloyDB. Nesta página, descrevemos como usar a MCP Toolbox for Databases para expor suas ferramentas de assistência ao desenvolvedor a uma instância do AlloyDB usando o seguinte ambiente de desenvolvimento integrado (IDE):

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

Antes de começar

Verifique se você tem os papéis necessários.

Funções exigidas

Para se conectar à instância do AlloyDB, você precisa dos seguintes papéis ou permissões equivalentes do Identity and Access Management (IAM):

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

Configurar o banco de dados

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. Ative as APIs do Cloud necessárias para criar e se conectar ao AlloyDB para PostgreSQL.

   Ative as APIs

   1. Na etapa Confirmar projeto, clique em Próxima para confirmar o nome do projeto em que você vai fazer mudanças.

   2. Na etapa Ativar APIs, clique em Ativar para ativar o seguinte:

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

      A API Service Networking é necessária se você planeja configurar a conectividade de rede com o AlloyDB usando uma rede VPC que reside no mesmo projeto Google Cloud do AlloyDB.

      As APIs Compute Engine e Cloud Resource Manager são necessárias se você planeja configurar a conectividade de rede com o AlloyDB usando uma rede VPC que reside em um projeto Google Cloud diferente.

2. Crie ou selecione um cluster e a instância principal dele. A caixa de ferramentas do MCP se conecta com segurança à sua instância usando os Conectores de Linguagem do AlloyDB.
3. Configure as Credenciais padrão do aplicativo (ADC) para seu ambiente.
4. Crie ou reutilize um usuário de banco de dados. Tenha o nome de usuário e a senha em mãos.

Instalar a caixa de ferramentas do MCP

1. Faça o download da versão mais recente da MCP Toolbox como um binário. Selecione o binário correspondente ao seu sistema operacional e à arquitetura da CPU. Use a versão V0.7.0 ou mais recente 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. Torne o binário executável.

   chmod +x toolbox
   

3. Verifique a instalação.

   ./toolbox --version
   

Configurar o cliente MCP

Código do Claude

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




{
  "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 para computador e acesse Configurações.
2. Na guia Desenvolvedor, clique em Editar configuração para abrir o arquivo de configuração.
3. Adicione a configuração, substitua as variáveis de ambiente pelos seus valores e salve.




{
  "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. A nova tela de chat mostra 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 arquivo de configuração.
3. Adicione a seguinte configuração, substitua as variáveis de ambiente pelos seus valores e salve.




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


Um status ativo verde aparece depois que o servidor se conecta.



Cursor

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

{
  "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 Cursor e navegue até Configurações > Configurações do cursor > MCP. Um status verde ativo aparece quando o servidor se conecta.

Visual Studio Code (Copilot)

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

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

{
  "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 diretório de trabalho, crie uma pasta chamada .gemini. Nele, crie um arquivo settings.json.
3. Adicione a configuração a seguir, substitua as variáveis de ambiente pelos seus valores e salve.

{
  "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 Agente no chat do Gemini Code Assist.
3. No diretório de trabalho, crie uma pasta chamada .gemini. Nele, crie um arquivo settings.json.
4. Adicione a configuração a seguir, substitua as variáveis de ambiente pelos seus valores e salve.

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

Usar ferramentas de IA

Sua ferramenta de IA agora está conectada ao AlloyDB usando o MCP. Peça ao assistente de IA para listar tabelas, criar uma tabela ou definir e executar outras instruções SQL.

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

• list_tables: lista tabelas e descrições.
• execute_sql: executa qualquer instrução SQL.
Observação: as ferramentas pré-criadas são anteriores à versão 1.0. Portanto, espere algumas mudanças entre as versões. Os LLMs se adaptam às ferramentas disponíveis, então isso não afeta a maioria dos usuários.