Use o Spanner com a MCP Toolbox for Databases, a CLI do Gemini e outros agentes

Este documento descreve como ligar a sua instância do Spanner a várias ferramentas para programadores que suportam o protocolo de contexto do modelo (MCP).

Recomendamos a utilização da extensão do Spanner dedicada para a CLI do Gemini. Esta extensão abstrai a necessidade de configurar uma ligação de servidor separada. Pode configurar o Gemini Code Assist para usar a CLI do Gemini, oferecendo vantagens de configuração semelhantes no seu IDE. Para mais informações, consulte o artigo Extensão da CLI do Gemini – Spanner.

Em alternativa, outros IDEs e ferramentas para programadores que suportem o MCP podem estabelecer ligação através da caixa de ferramentas do MCP para bases de dados. A caixa de ferramentas MCP é um servidor MCP de código aberto concebido para ligar agentes de IA aos seus dados. Processa tarefas como a autenticação e a partilha de ligações, o que lhe permite interagir com os seus dados com linguagem natural diretamente a partir do IDE.

Use a extensão da CLI Gemini no Spanner

Nota: a caixa de ferramentas do MCP para bases de dados está em versão beta (pré-v1.0) e pode sofrer alterações destrutivas até ao primeiro lançamento estável. (v1.0)

A integração do Spanner com a CLI do Gemini é feita através de uma extensão de código aberto que oferece capacidades adicionais em comparação com a ligaçã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 a instalação, a configuração e exemplos de utilização. Se usar a extensão da CLI Gemini, não precisa de 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	Que tabelas tenho na minha instância do Spanner?
execute_sql	Insira dados de teste na tabela de produtos.
execute_sql_dql	Que produtos na categoria de eletrónica são vendidos na América?

Antes de começar

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

2. Certifique-se de que a faturação está ativada para o seu Google Cloud projeto.

Configure a instância do Spanner

1. Ative a API Spanner no Google Cloud projeto.

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

3. Configure as funções e as autorizações necessárias para concluir esta tarefa. O utilizador que invoca os agentes do MDG precisa das seguintes funções ao nível da base de dados:

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

   • Utilizador da base de dados do Cloud Spanner (roles/spanner.databaseUser) para executar consultas DML.

4. Configure as Credenciais padrão da aplicação (ADC) para o seu ambiente.

Instale a caixa de ferramentas do MCP

Nota: a caixa de ferramentas do MCP só é necessária para clientes do MCP que não sejam a CLI do Gemini nem o Gemini Code Assist. Ignore esta secção se estiver a usar a CLI do Gemini ou o Gemini Code Assist.

1. Transfira a versão mais recente da MCP Toolbox como um ficheiro binário. Selecione o binário correspondente ao seu sistema operativo (SO) e arquitetura da CPU. Tem de usar a versão 0.15.0 ou posterior 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 executável binário:

   chmod +x toolbox
   

3. Valide a instalação:

   ./toolbox --version
   

Configure a ferramenta de agente

Esta secção descreve como configurar várias ferramentas para programadores para estabelecer ligação à sua instância do Spanner. Selecione a ferramenta de agente nas seguintes opções:

CLI do Gemini

1. Instale a CLI do Gemini.
   
2. Instale a extensão Spanner para a Gemini CLI a partir do repositório do GitHub com o seguinte comando:
   

  gemini extensions install https://github.com/gemini-cli-extensions/spanner
  

3. Defina as seguintes variáveis de ambiente para estabelecer ligação à 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 o seguinte:
   • PROJECT_ID: o ID do seu Google Cloud projeto.
   • INSTANCE_NAME: o nome da sua instância do Spanner.
   • DATABASE_NAME: o nome da base de dados do Spanner.
   • DIALECT_NAME: o dialeto de SQL do Spanner. Aceita googlesql ou postgresql. A predefinição é googlesql se não estiver definida.
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 respetivas ferramentas, que pode usar para interagir com a sua base de dados.

Gemini Code Assist

Recomendamos vivamente que configure o Gemini Code Assist para usar a CLI do Gemini, uma vez que esta abordagem elimina a necessidade de configurar manualmente um servidor MCP. No entanto, as instruções para configurar manualmente um servidor MCP continuam disponíveis na secção seguinte:

1. Instale a extensão 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 com o nome .gemini e, dentro desta, um ficheiro settings.json.
4. Adicione uma das seguintes configurações com base no seu dialeto do Spanner no ficheiro settings.json.
5. Substitua as seguintes variáveis pelos seus valores:

• PROJECT_ID: o ID do seu Google Cloud projeto.
• INSTANCE_NAME: o nome da sua instância do Spanner.
• DATABASE_NAME: o nome da base de dados do Spanner.

6. Guarde o ficheiro.

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

Código Claude

1. Instale o Claude Code.
2. Crie o ficheiro .mcp.json na raiz do projeto, se não existir.
3. Adicione uma das seguintes configurações com base no seu dialeto do Spanner, substitua as variáveis de ambiente pelos seus valores e guarde o ficheiro:

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 navegue para Definições.
2. No separador Programador, clique em Editar configuração para abrir o ficheiro de configuraçã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 guarde o ficheiro:

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. O novo ecrã de chat apresenta 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 ficheiro de configuraçã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 guarde o ficheiro:

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

É apresentado um estado ativo verde depois de o servidor se ligar com êxito.

Cursor

1. Crie o diretório .cursor na raiz do projeto, se não existir.
2. Crie o ficheiro .cursor/mcp.json se 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 guarde o ficheiro:

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 navegue para Definições > Definições do cursor > MCP. É apresentado um estado ativo verde quando o servidor se liga.

Visual Studio Code (Copilot)

1. Abra o VS Code e crie o diretório .vscode na raiz do projeto, se não existir.
2. Crie o ficheiro .vscode/mcp.json, se 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 guarde o ficheiro:

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 para o assistente Cascade.
2. Clique no ícone do MCP e, de seguida, em Configurar para abrir o ficheiro de configuraçã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 guarde o ficheiro:

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