Conectar LLMs ao Cloud Storage com o MCP

Este guia mostra como conectar o Cloud Storage a ambientes de desenvolvimento integrado (IDEs) e ferramentas para desenvolvedores. Para fazer isso, execute um servidor MCP local na sua máquina usando a MCP Toolbox for Databases.

A MCP Toolbox for Databases é um repositório de código aberto que contém conectores para bancos de dados e datastores, incluindo Cloud Storage, BigQuery, AlloyDB, Spanner e Cloud SQL. A caixa de ferramentas oferece suporte à autenticação OAuth2 e OIDC e se integra ao Open Telemetry para observabilidade. A integração da caixa de ferramentas do Cloud Storage permite usar um LLM para realizar as seguintes ações:

  • Criar, listar e excluir buckets.
  • Acessar metadados de buckets e objetos.
  • Acessar políticas do Identity and Access Management (IAM) nos buckets.
  • Ler, gravar, fazer upload e download de objetos.
  • Copiar ou mover objetos.

Este guia demonstra o processo de conexão para os seguintes IDEs e ferramentas:

  • Cursor
  • Windsurf (antigo Codeium)
  • Visual Studio Code (Copilot)
  • Cline (extensão do VS Code)
  • Claude Desktop
  • Claude Code
  • Antigravity

Antes de começar

  1. No Cloud de Confiance console do, na página do seletor de projetos, selecione ou crie um Cloud de Confiance by S3NS projeto do.

  2. Verifique se o faturamento está ativado para o projeto do Cloud de Confiance .

  3. Ative a API Storage do Cloud Storage no Cloud de Confiance projeto.

  4. Configure os papéis e permissões necessários para concluir esta tarefa. O usuário que invoca os agentes LLM precisa dos seguintes papéis no nível do bucket ou do projeto:

    • Para listar buckets, criar buckets e excluir buckets vazios: Administrador do Storage (roles/storage.admin)
    • Para listar objetos, ler objetos, acessar metadados de objetos ou metadados de buckets: Leitor de objetos do Storage (roles/storage.objectViewer)
    • Para gravar conteúdo em um objeto ou fazer upload de um objeto: Criador de objetos do Storage (roles/storage.objectCreator)
    • Para copiar, mover ou excluir objetos: Administrador de objetos do Storage (roles/storage.objectAdmin)

  5. Configure o Application Default Credentials (ADC) para seu ambiente.

Conectar com o Antigravity

Você conecta o Cloud Storage ao Antigravity usando uma configuração personalizada. Nesse contexto, um servidor MCP personalizado é um servidor que você configura manualmente editando o arquivo de configuração (como mcp_config.json). Essa configuração manual é usada em vez de instalar o servidor diretamente no catálogo da loja do MCP integrada.

Para configurar um servidor MCP personalizado, faça o seguinte:

  1. Verifique se o npx está instalado e configurado corretamente no seu sistema executando npx --version no terminal. Se você precisar instalar o Node.js, que inclui o npx, consulte o guia de download e instalação do Node.js e do npm.
  2. Abra Antigravity e navegue até a loja do MCP usando o menu suspenso "..." na parte de cima do painel do agente do editor.
  3. Para abrir o arquivo mcp_config.json, clique em Servidores MCP e em Gerenciar servidores MCP > Ver configuração bruta.
  4. Adicione a seguinte configuração, substitua o marcador de posição pelo ID do projeto e salve: 
    {
  "mcpServers": {
    "storage": {
      "command": "npx",
      "args": ["-y","@toolbox-sdk/server","--prebuilt","cloud-storage","--stdio"],
      "env": {
          "CLOUD_STORAGE_PROJECT": "PROJECT_ID"
      }
    }
  }
}

Instalar a MCP Toolbox

A caixa de ferramentas é um servidor de protocolo de contexto de modelo (MCP, na sigla em inglês) de código aberto que é executado localmente na sua máquina. O servidor local gerencia a comunicação entre o IDE e o Cloud Storage. Essa conexão oferece um ambiente seguro e eficiente para suas ferramentas de IA.

  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 (SO) e à arquitetura de CPU. É necessário usar a MCP Toolbox versão 1.2.0 ou mais recente:

    linux/amd64

    curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/VERSION/linux/amd64/toolbox

    Substitua VERSION pela versão da MCP Toolbox, por exemplo, v1.2.0.

    macOS darwin/arm64

    curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/VERSION/darwin/arm64/toolbox

    Substitua VERSION pela versão da MCP Toolbox, por exemplo, v1.2.0.

    macOS darwin/amd64

    curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/VERSION/darwin/amd64/toolbox

    Substitua VERSION pela versão da MCP Toolbox, por exemplo, v1.2.0.

    windows/amd64

    curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/VERSION/windows/amd64/toolbox

    Substitua VERSION pela versão da MCP Toolbox, por exemplo, v1.2.0.

  2. Torne o binário executável:

    chmod +x toolbox

  3. Verifique a instalação:

    ./toolbox --version

Para configurar a caixa de ferramentas com uma imagem de contêiner ou o Homebrew, consulte a página Instalar a caixa de ferramentas.

Configurar clientes e conexões

Esta seção descreve como conectar o Cloud Storage às suas ferramentas depois de instalar a MCP Toolbox.

Claude Code

  1. Instale o Claude Code.
  2. Crie um arquivo .mcp.json na raiz do projeto, se ele não existir.
  3. Adicione a configuração, substitua os marcadores pelos seus valores e salve: 
            {
          "mcpServers": {
            "storage": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","cloud-storage","--stdio"],
              "env": {
                "CLOUD_STORAGE_PROJECT": "PROJECT_ID"
              }
            }
          }
        }
    Substitua as seguintes variáveis pelos seus valores:
    • ./PATH/TO/toolbox: o caminho para o binário toolbox.
    • CLOUD_STORAGE_PROJECT: a variável de ambiente que especifica o Cloud de Confiance ID do projeto.
    • PROJECT_ID: o ID do projeto do Cloud de Confiance by S3NS .
  4. Reinicie o Claude Code para carregar as novas configurações. Quando o Claude Code for reaberto, o aplicativo vai detectar o servidor MCP configurado.

Claude Desktop

  1. Abra o Claude Desktop e navegue até Configurações.
  2. Na guia Desenvolvedor, clique em Editar configuração para abrir o arquivo de configuração.
  3. Adicione a configuração, substitua os marcadores pelos seus valores e salve: 
            {
          "mcpServers": {
            "storage": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","cloud-storage","--stdio"],
              "env": {
                "CLOUD_STORAGE_PROJECT": "PROJECT_ID"
              }
            }
          }
        }
    Substitua as seguintes variáveis pelos seus valores:
    • ./PATH/TO/toolbox: o caminho para o binário toolbox.
    • CLOUD_STORAGE_PROJECT: a variável de ambiente que especifica o ID do projeto. Cloud de Confiance
    • PROJECT_ID: o ID do projeto do Cloud de Confiance by S3NS .
  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 clique no ícone Servidores MCP.
  2. Clique em Configurar servidores MCP para abrir o arquivo de configuração.
  3. Adicione a seguinte configuração, substitua os marcadores pelos seus valores e salve: 
            {
          "mcpServers": {
            "storage": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","cloud-storage","--stdio"],
              "env": {
                "CLOUD_STORAGE_PROJECT": "PROJECT_ID"
              }
            }
          }
        }
    Substitua as seguintes variáveis pelos seus valores:
    • ./PATH/TO/toolbox: o caminho para o binário toolbox.
    • CLOUD_STORAGE_PROJECT: a variável de ambiente que especifica o Cloud de Confiance ID do projeto.
    • PROJECT_ID: o ID do projeto do Cloud de Confiance by S3NS .

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 os marcadores pelos seus valores e salve: 
            {
          "mcpServers": {
            "storage": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","cloud-storage","--stdio"],
              "env": {
                "CLOUD_STORAGE_PROJECT": "PROJECT_ID"
              }
            }
          }
        }
    Substitua as seguintes variáveis pelos seus valores:
    • ./PATH/TO/toolbox: o caminho para o binário toolbox.
    • CLOUD_STORAGE_PROJECT: a variável de ambiente que especifica o ID do projeto. Cloud de Confiance
    • PROJECT_ID: o ID do projeto do Cloud de Confiance by S3NS .
  4. Abra o Cursor e navegue até Configurações > Configurações do cursor > MCP. Um status ativo verde aparece quando o servidor se conecta.

Visual Studio Code (Copilot)

  1. Abra o VS Code e crie um 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 os marcadores pelos seus valores e salve: 
            {
          "mcpServers": {
            "storage": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","cloud-storage","--stdio"],
              "env": {
                "CLOUD_STORAGE_PROJECT": "PROJECT_ID"
              }
            }
          }
        }
    Substitua as seguintes variáveis pelos seus valores:
    • ./PATH/TO/toolbox: o caminho para o binário toolbox.
    • CLOUD_STORAGE_PROJECT: a variável de ambiente que especifica o ID do projeto. Cloud de Confiance
    • PROJECT_ID: o ID do projeto do Cloud de Confiance by S3NS .
  4. Recarregue a janela do VS Code. A extensão compatível com MCP detecta automaticamente a configuração e inicia o servidor.

Windsurf

  1. Abra o Windsurf e navegue até o assistente Cascade.
  2. Clique no ícone do MCP e em Configurar para abrir o arquivo de configuração.
  3. Adicione a seguinte configuração, substitua os marcadores pelos seus valores e salve: 
            {
          "mcpServers": {
            "storage": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","cloud-storage","--stdio"],
              "env": {
                "CLOUD_STORAGE_PROJECT": "PROJECT_ID"
              }
            }
          }
        }
    Substitua as seguintes variáveis pelos seus valores:
    • ./PATH/TO/toolbox: o caminho para o binário toolbox.
    • CLOUD_STORAGE_PROJECT: a variável de ambiente que especifica o Cloud de Confiance ID do projeto.
    • PROJECT_ID: o ID do projeto do Cloud de Confiance by S3NS .

Ferramentas pré-criadas

Depois de conectar a MCP Toolbox ao Cloud Storage, o agente usa as seguintes ferramentas pré-criadas:

  • list_buckets: lista os buckets do Cloud Storage no projeto configurado.
  • list_objects: lista objetos em um bucket com filtragem opcional de prefixo e delimitador.
  • get_bucket_metadata: retorna metadados de um bucket.
  • get_bucket_iam_policy: retorna as vinculações da política de IAM de um bucket.
  • get_object_metadata: retorna metadados de um objeto.
  • read_object: lê um objeto de texto UTF-8 (ou intervalo de bytes). Limitado a 8 MiB; objetos binários são rejeitados.
  • download_object: faz o download de um objeto para um caminho local.
  • create_bucket: cria um bucket no projeto configurado.
  • delete_bucket: exclui um bucket vazio.
  • upload_object: faz o upload de um arquivo local para um objeto.
  • write_object: grava conteúdo de texto diretamente em um objeto.
  • copy_object: copia um objeto para um objeto de destino.
  • move_object: renomeia atomicamente um objeto no mesmo bucket.
  • delete_object: exclui um objeto.