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. Você pode 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 e ferramentas de desenvolvedor que oferecem suporte ao MCP podem se conectar usando o MCP Toolbox for Databases. O 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 pool de conexões, permitindo que você interaja com seus dados usando 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 adicionais 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ê usar a extensão da CLI do Gemini, não precisará instalar o MCP Toolbox. 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 todas as habilidades disponíveis, consulte as habilidades do Spanner no GitHub.

Antes de começar

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

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 permissões necessários para concluir essa tarefa. O usuário que invoca os agentes LLM precisa dos seguintes papéis 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 DML.

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

Instalar o MCP Toolbox

Observação: o MCP Toolbox só é necessário para clientes MCP que não sejam a CLI do Gemini, o Gemini Code Assist ou o Antigravity. Pule esta seção se você estiver usando a CLI do Gemini, o Gemini Code Assist ou o Antigravity.

1. Faça o download da versão mais recente do 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 do 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

Esta seção descreve como configurar várias ferramentas de desenvolvedor para se conectar à sua instância do Spanner. Selecione seu cliente nas 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 Google Cloud ID do projeto.
   • 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 podem ser usadas para interagir com o banco de dados.

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

Gemini Code Assist

Recomendamos configurar o Gemini Code Assist para usar a CLI do Gemini, porque 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 do Gemini Code Assist no VS Code.
2. Ative o modo de 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 dialeto do Spanner no arquivo settings.json.
5. Substitua as variáveis a seguir pelos seus valores:

• PROJECT_ID: o ID do Google Cloud projeto.
• 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 à 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 Google Cloud ID do projeto.
   • 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

Dica:execute /plugin list no Claude Code para verificar se o plug-in está ativo ou /reload-plugins se você acabou de instalá-lo.

Codex

1. Instale o marketplace do Data Agent Kit:

   codex plugin marketplace add GoogleCloudPlatform/data-agent-kit

2. Instale o plug-in do Spanner:

   codex plugin install spanner@data-agent-kit

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 Google Cloud ID do projeto.
   • 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-agent-kit

Claude for Desktop

1. Abra o Claude for Desktop 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 for 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. 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 seu 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 o Cursor e acesse Configurações > Configurações do cursor > MCP. Um status ativo verde aparece quando o servidor se conecta.

Visual Studio Code (Copilot)

1. Abra 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 acesse o assistente do Cascade.
2. Clique no ícone 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"
      }
    }
  }
}

Conectar com o Antigravity

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

• Usando a MCP Store
• Usando uma configuração personalizada

MCP Store

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 o 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 MCP Store, os recursos e habilidades do servidor 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 seguinte configuração, 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 habilidades do servidor do Spanner ficam disponíveis para o editor.

Substitua:

• PROJECT_ID: o ID do Google Cloud projeto.
• 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. Se você não especificar um dialeto, o padrão será googlesql.

Conectar ao Spanner usando o Data Agent Kit

Visualizar

Esse produto ou recurso está sujeito aos "Termos de ofertas pré-GA" na seção "Termos gerais de serviço" dos Termos específicos de serviço. Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

O Data Agent Kit do Google Cloud permite gerenciar o banco de dados do Spanner e executar consultas nos dados do Spanner no seu ambiente de desenvolvimento integrado ou agente de programação preferido. A extensão do Data Agent Kit funciona com o Visual Studio Code e ambientes de desenvolvimento integrado 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 exploração de dados, permitindo que você faça perguntas sobre os dados do Spanner em linguagem natural. Ele ajuda a eliminar a troca de contexto entre as ferramentas de linha de comando do Spanner e o ambiente de desenvolvimento.

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