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

Neste documento, descrevemos como conectar sua instância do Spanner a várias ferramentas para desenvolvedores que oferecem suporte ao Protocolo de Contexto de Modelo (MCP).

Recomendamos usar a extensão dedicada do Spanner para a CLI Gemini. Essa extensão elimina a necessidade de configurar uma conexão de servidor separada. É 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 IDEs e ferramentas de desenvolvedor 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 usando linguagem natural diretamente do seu ambiente de desenvolvimento integrado.

Usar a extensão da CLI do Gemini no Spanner

Observação: a caixa de ferramentas do MCP para bancos de dados está na versão Beta (pré-v1.0) e pode ter mudanças significativas até o primeiro lançamento estável. (v1.0)

A integração do Spanner com a CLI do Gemini é feita por uma extensão de código aberto que oferece mais recursos em comparação com a conexão padrão da caixa de ferramentas do MCP. A extensão oferece um processo de instalação e um conjunto de ferramentas, além de fornecer informações detalhadas sobre instalação, configuração e exemplos de uso. Se você usa a extensão da CLI do Gemini, não precisa instalar a caixa de ferramentas do MCP. Para mais informações, consulte Extensão da CLI do Gemini - Spanner.

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

Ferramentas	Exemplo de comando de linguagem natural
list_tables	Quais tabelas eu tenho na minha instância do Spanner?
execute_sql	Insira dados de teste na tabela de produtos.
execute_sql_dql	Quais produtos da categoria de eletrônicos são vendidos na América?

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 seu 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 do 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 as Credenciais padrão do aplicativo (ADC) para seu ambiente.

Instalar a caixa de ferramentas do MCP

Observação: a caixa de ferramentas do MCP é necessária apenas para clientes do MCP que não sejam a CLI do Gemini ou o Gemini Code Assist. Pule esta seção se você estiver usando a CLI do Gemini ou o Gemini Code Assist.

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 0.15.0 ou mais recente da MCP Toolbox:

   linux/amd64

   curl -O https://storage.googleapis.com/genai-toolbox/version/linux/amd64/toolbox
   
   

   darwin/arm64

   curl -O https://storage.googleapis.com/genai-toolbox/version/darwin/arm64/toolbox
   
   

   darwin/amd64

   curl -O https://storage.googleapis.com/genai-toolbox/version/darwin/amd64/toolbox
   
   

   windows/amd64

   curl -O https://storage.googleapis.com/genai-toolbox/version/windows/amd64/toolbox
   
   

2. Torne o binário executável:

   chmod +x toolbox
   

3. Verifique a instalação:

   ./toolbox --version
   

Configurar a ferramenta de agente

Nesta seção, descrevemos como configurar várias ferramentas de desenvolvedor para se conectar à sua instância do Spanner. Selecione sua ferramenta de agente em uma das 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 variáveis de ambiente a seguir 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 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 do Spanner SQL. Aceita googlesql ou postgresql. O padrão é googlesql se não for 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 ferramentas dela, que podem ser usadas para interagir com seu banco de dados.

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 do 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 o 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. Crie o arquivo .mcp.json na raiz do projeto, se ele não existir.
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"
      }
    }
  }
}

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