Usar o Spanner com a caixa de ferramentas do MCP para bancos de dados, a CLI do Gemini e outros agentes

Este documento descreve como conectar sua instância do Spanner a várias ferramentas de desenvolvedor que oferecem suporte ao Protocolo de Contexto de Modelo (MCP).

Recomendamos usar a extensão dedicada do Spanner para a CLI do Gemini. A extensão agrupa as habilidades subjacentes diretamente nela, o que simplifica a configuração. É possível configurar o Gemini Code Assist para usar a CLI do Gemini, oferecendo benefícios de configuração semelhantes no seu ambiente de desenvolvimento integrado. Para mais informações, consulte Extensão da CLI do Gemini: Spanner.

Como alternativa, outros ambientes de desenvolvimento integrado (IDEs) e ferramentas para desenvolvedores que oferecem suporte ao MCP podem se conectar usando a MCP Toolbox for Databases. A MCP Toolbox é um servidor MCP de código aberto projetado para conectar agentes de IA aos seus dados. Ele processa tarefas como autenticação e agrupamento de conexões, permitindo que você interaja com seus dados em linguagem natural diretamente do seu ambiente de desenvolvimento integrado.

Usar a extensão da CLI do Gemini no Spanner

A integração do Spanner com a CLI do Gemini é feita por uma extensão de código aberto que oferece recursos extras em comparação com a conexão padrão do MCP Toolbox. A extensão oferece um processo de instalação simplificado e um conjunto de habilidades com base nas ferramentas do MCP. Se você usa a extensão da CLI do Gemini, não é necessário instalar a caixa de ferramentas do MCP. Para mais informações, consulte Extensão da CLI do Gemini - Spanner.

A extensão spanner inclui habilidades para listar tabelas e executar instruções SQL e SQL DQL.

Para conferir todas as habilidades disponíveis, consulte as habilidades do Spanner no GitHub (link em inglês).

Antes de começar

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

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

Configurar a instância do Spanner

  1. Ative a API Spanner no Google Cloud projeto.

  2. Crie ou selecione uma instância e um banco de dados do Spanner.

  3. Configure os papéis e as permissões necessárias para concluir essa tarefa. O usuário que invoca os agentes de LLM precisa das seguintes funções no nível do banco de dados:

    • Leitor de banco de dados do Cloud Spanner (roles/spanner.databaseReader) para executar consultas DQL e listar tabelas.

    • Usuário do banco de dados do Cloud Spanner (roles/spanner.databaseUser) para executar consultas de DML.

  4. Configure as Application Default Credentials (ADC) para seu ambiente.

Instalar o MCP Toolbox

  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. Use a versão 0.15.0 ou mais recente da MCP Toolbox:

    linux/amd64

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

    darwin/arm64

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

    darwin/amd64

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

    windows/amd64

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

  2. Torne o binário executável:

    chmod +x toolbox

  3. Verifique a instalação:

    ./toolbox --version

Configurar clientes e conexões

Nesta seção, descrevemos como configurar várias ferramentas de desenvolvedor para se conectar à instância do Spanner. Selecione seu cliente entre as seguintes opções:

CLI do Gemini

  1. Instale a CLI do Gemini.
  2. Instale a extensão do Spanner para a CLI do Gemini no repositório do GitHub usando o seguinte comando: 
    gemini extensions install https://github.com/gemini-cli-extensions/spanner
  3. Defina as seguintes variáveis de ambiente para se conectar à sua instância do Spanner: 
    export SPANNER_PROJECT="PROJECT_ID"
export SPANNER_INSTANCE="INSTANCE_NAME"
export SPANNER_DATABASE="DATABASE_NAME"
export SPANNER_DIALECT="DIALECT_NAME"
     Substitua:
    • PROJECT_ID: o ID do projeto do Google Cloud .
    • INSTANCE_NAME: o nome da instância do Spanner.
    • DATABASE_NAME: o nome do banco de dados do Spanner.
    • DIALECT_NAME: o dialeto SQL do Spanner. Aceita googlesql ou postgresql. O padrão é googlesql se não estiver definido.
  4. Inicie a CLI do Gemini no modo interativo: 
    gemini

    A CLI carrega automaticamente a extensão do Spanner para a CLI do Gemini e as habilidades dela, que você pode usar para interagir com seu banco de dados.

    Na CLI do Gemini, use o comando /extensions para verificar se a extensão está instalada.

Gemini Code Assist

Recomendamos configurar o Gemini Code Assist para usar a CLI do Gemini, já que essa abordagem elimina a necessidade de configurar manualmente um servidor MCP. No entanto, as instruções para configurar manualmente um servidor MCP ainda estão disponíveis na seção a seguir:


1. Instale a extensão Gemini Code Assist no VS Code.
2. Ative o modo agente e mude o modelo de agente para o Gemini.
3. No diretório raiz do projeto, crie uma pasta chamada .gemini e, dentro dela, um arquivo settings.json.
4. Adicione uma das seguintes configurações com base no seu dialeto do Spanner no arquivo settings.json.
5. Substitua as seguintes variáveis pelos seus valores:
  • PROJECT_ID: o ID do projeto Google Cloud .
  • INSTANCE_NAME: o nome da instância do Spanner.
  • DATABASE_NAME: o nome do banco de dados do Spanner.
6. Salve o arquivo.

Spanner com dialeto GoogleSQL: 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Spanner com dialeto PostgreSQL: 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner-postgres","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Claude Code

  1. Instale o Claude Code.
  2. Defina as variáveis de ambiente para se conectar à instância do Spanner: 
    export SPANNER_PROJECT="PROJECT_ID"
export SPANNER_INSTANCE="INSTANCE_NAME"
export SPANNER_DATABASE="DATABASE_NAME"
export SPANNER_DIALECT="DIALECT_NAME"
     Substitua:
    • PROJECT_ID: o ID do projeto do Google Cloud .
    • INSTANCE_NAME: o nome da instância do Spanner.
    • DATABASE_NAME: o nome do banco de dados do Spanner.
    • DIALECT_NAME: o dialeto SQL do Spanner. Aceita googlesql ou postgresql. O padrão é googlesql se não estiver definido.
  3. Inicie o agente: 
    claude
  4. Instalar o plug-in: 
    /plugin install spanner@claude-plugins-official

Codex

  1. Instale o marketplace de plug-ins da Data Cloud: 
    codex plugin marketplace add GoogleCloudPlatform/data-cloud-plugins
  2. Instale o plug-in do Spanner: 
    codex plugin install spanner@data-cloud-plugins
  3. Configure as variáveis de ambiente para se conectar à sua instância do Spanner: 
    export SPANNER_PROJECT="PROJECT_ID"
export SPANNER_INSTANCE="INSTANCE_NAME"
export SPANNER_DATABASE="DATABASE_NAME"
export SPANNER_DIALECT="DIALECT_NAME"
     Substitua:
    • PROJECT_ID: o ID do projeto do Google Cloud .
    • INSTANCE_NAME: o nome da instância do Spanner.
    • DATABASE_NAME: o nome do banco de dados do Spanner.
    • DIALECT_NAME: o dialeto SQL do Spanner. Aceita googlesql ou postgresql. O padrão é googlesql se não estiver definido.
  4. Opcional. Atualize o marketplace: 
    codex plugin marketplace upgrade data-cloud-plugins

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 uma das seguintes configurações com base no dialeto do Spanner, substitua as variáveis de ambiente pelos seus valores e salve o arquivo:

Spanner com dialeto GoogleSQL: 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Spanner com dialeto PostgreSQL: 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner-postgres","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

4. Reinicie o Claude para computador.
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. Toque em "Configurar servidores MCP" para abrir o arquivo de configuração.
3. Adicione uma das seguintes configurações com base no dialeto do Spanner, substitua as variáveis de ambiente pelos seus valores e salve o arquivo:

Spanner com dialeto GoogleSQL: 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Spanner com dialeto PostgreSQL: 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner-postgres","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

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 uma das seguintes configurações com base no dialeto do Spanner, substitua as variáveis de ambiente pelos seus valores e salve o arquivo:

Spanner com dialeto GoogleSQL: 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Spanner com dialeto PostgreSQL: 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner-postgres","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

4. Abra 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 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 uma das seguintes configurações com base no dialeto do Spanner, substitua as variáveis de ambiente pelos seus valores e salve o arquivo:

Spanner com dialeto GoogleSQL: 

{
  "servers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
        "SPANNER_PROJECT": "PROJECT_ID",
        "SPANNER_INSTANCE": "INSTANCE_NAME",
        "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Spanner com dialeto PostgreSQL: 

{
  "servers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner-postgres","--stdio"],
      "env": {
        "SPANNER_PROJECT": "PROJECT_ID",
        "SPANNER_INSTANCE": "INSTANCE_NAME",
        "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

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 uma das seguintes configurações com base no dialeto do Spanner, substitua as variáveis de ambiente pelos seus valores e salve o arquivo:

Spanner com dialeto GoogleSQL: 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Spanner com dialeto PostgreSQL: 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner-postgres","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Conecte-se com o Antigravity

É possível conectar o Spanner ao Antigravity das seguintes maneiras:

  • Como usar a loja do MCP
  • Usar uma configuração personalizada

Loja do MCP

A maneira mais recomendada de se conectar ao Antigravity é usando a MCP Store integrada.

  1. Abra o Antigravity e o painel do agente do editor.
  2. Clique no ícone Menu na parte de cima do painel e selecione Servidores MCP.
  3. Localize Spanner na lista de servidores disponíveis e clique em Instalar.
  4. Siga as etapas na tela para autorizar o Antigravity a acessar seu projeto do Google Cloud. Isso permite que o Antigravity acesse a instância do Spanner no seu projeto.

Depois de instalar o servidor do Spanner na loja do MCP, os recursos e as habilidades dele ficam disponíveis para o editor.

Configuração personalizada

Para se conectar a um servidor MCP personalizado, siga estas etapas:

  1. Abra o Antigravity e o painel do agente do editor.
  2. Clique no ícone Menu na parte de cima do painel e selecione Servidores MCP.
  3. Clique em Gerenciar servidores MCP > Ver configuração bruta para abrir o arquivo mcp_config.json.
  4. Adicione a configuração a seguir, substitua as variáveis de ambiente pelos seus valores e salve.
{
  "mcpServers": {
    "spanner": {
      "command": "npx",
      "args": ["-y","@toolbox-sdk/server","--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME",
          "SPANNER_DIALECT": "DIALECT_NAME"
      }
    }
  }
}

Depois de configurar o servidor MCP personalizado, os recursos e as habilidades do servidor do Spanner ficam disponíveis para o editor.

Substitua:

  • PROJECT_ID: o ID do projeto Google Cloud .
  • INSTANCE_NAME: o nome da instância do Spanner.
  • DATABASE_NAME: o nome do banco de dados do Spanner.
  • DIALECT_NAME: seu dialeto SQL do Spanner. Aceita googlesql ou postgresql. Se você não especificar um dialeto, o padrão será googlesql.

Conectar-se ao Spanner usando o Data Agent Kit

Com o Google Cloud Data Agent Kit, é possível gerenciar seu banco de dados do Spanner e executar consultas nos dados do Spanner no ambiente de desenvolvimento integrado ou agente de programação preferido. A extensão do Data Agent Kit funciona com o Visual Studio Code e IDEs baseados no VS Code, e o plug-in do Data Agent Kit funciona com vários agentes de programação conhecidos, incluindo o Claude Code e a CLI do Codex.

O Data Agent Kit oferece recursos de descoberta e análise de dados, permitindo que você faça perguntas sobre seus dados do Spanner em linguagem natural. Ele ajuda a eliminar a troca de contexto entre ferramentas de linha de comando do Spanner e seu ambiente de desenvolvimento.

Para mais informações, consulte Visão geral do Data Agent Kit.