Codelab: servidor MCP do Spanner

1. Visão geral

Este codelab demonstra como emitir consultas de gráficos no Spanner usando o gemini-cli e os servidores do Protocolo de Contexto de Modelo (MCP) do Google. Ao integrar o banco de dados multimodelos do Spanner, incluindo o Spanner Graph, com o serviço MCP gerenciado, você pode usar a linguagem natural para descobrir relações ocultas nos seus dados, como círculos de fraude ou dependências da cadeia de suprimentos, em um único banco de dados sem escrever consultas complexas em GQL (linguagem de consulta de grafos) ou SQL manualmente.

43e1993ca796652e.png

O que você vai aprender

  • Como configurar um banco de dados multimodelos do Spanner, incluindo o Spanner Graph para MCP.
  • Como conectar a CLI do Gemini a um endpoint de serviço remoto gerenciado do Spanner.
  • Como usar a linguagem natural para gerar SQL integrado ao GQL automaticamente e realizar travessias de gráficos e correspondência de padrões com operações relacionais.
  • Práticas recomendadas para proteger dados de gráficos em fluxos de trabalho de IA.

Pré-requisitos

  • um projeto do Google Cloud com faturamento ativado
  • Acesso a um terminal (como o Cloud Shell). Consulte este codelab.
  • A CLI gcloud instalada e autenticada.
  • Acesso à CLI do Gemini.

OBSERVAÇÃO: você vai executar todos os comandos em um terminal Unix. Consulte os pré-requisitos acima para ter acesso a um terminal com acesso à gcloud e autenticação adequada.

2. Configurar o ambiente multimodelo do Spanner

O MCP gerenciado funciona melhor quando o esquema do banco de dados é predefinido. Vamos criar um gráfico financeiro de "Detecção de fraudes" com base nas amostras do Spanner Graph.

Ativar APIs

export PROJECT_ID="YOUR_PROJECT_ID"

gcloud config set project ${PROJECT_ID}

# Enable Spanner's MCP endpoint
gcloud beta services mcp enable spanner.googleapis.com --project=${PROJECT_ID}

Criar o esquema de banco de dados

Crie uma instância e um banco de dados com tabelas e um gráfico de propriedades. Esse esquema rastreia Contas, Pessoas e as Transferências entre elas.

OBSERVAÇÃO: é possível executar essas instruções DDL no Spanner Studio. Consulte este link para informações sobre como criar e consultar um banco de dados do Spanner no console do GCP.

CREATE TABLE Account (
  id INT64 NOT NULL,
  create_time TIMESTAMP,
  is_blocked BOOL,
  nick_name STRING(MAX),
) PRIMARY KEY(id);

CREATE TABLE Person (
  id INT64 NOT NULL,
  name STRING(MAX),
  birthday TIMESTAMP,
  country STRING(MAX),
  city STRING(MAX),
) PRIMARY KEY(id);

CREATE TABLE AccountTransferAccount (
  id INT64 NOT NULL,
  to_id INT64 NOT NULL,
  amount FLOAT64,
  create_time TIMESTAMP NOT NULL,
  order_number STRING(MAX),
  FOREIGN KEY(to_id) REFERENCES Account(id),
) PRIMARY KEY(id, to_id, create_time),
  INTERLEAVE IN PARENT Account ON DELETE CASCADE;

CREATE TABLE PersonOwnAccount (
  id INT64 NOT NULL,
  account_id INT64 NOT NULL,
  create_time TIMESTAMP,
  FOREIGN KEY(account_id) REFERENCES Account(id),
) PRIMARY KEY(id, account_id),
  INTERLEAVE IN PARENT Person ON DELETE CASCADE;

CREATE PROPERTY GRAPH FinGraph
  NODE TABLES(
    Account
      KEY(id)
      LABEL Account PROPERTIES(
        create_time,
        id,
        is_blocked,
        nick_name),

    Person
      KEY(id)
      LABEL Person PROPERTIES(
        birthday,
        city,
        country,
        id,
        name)
  )
  EDGE TABLES(
    AccountTransferAccount
      KEY(id, to_id, create_time)
      SOURCE KEY(id) REFERENCES Account(id)
      DESTINATION KEY(to_id) REFERENCES Account(id)
      LABEL Transfers PROPERTIES(
        amount,
        create_time,
        id,
        order_number,
        to_id),

    PersonOwnAccount
      KEY(id, account_id)
      SOURCE KEY(id) REFERENCES Person(id)
      DESTINATION KEY(account_id) REFERENCES Account(id)
      LABEL Owns PROPERTIES(
        account_id,
        create_time,
        id)
  );

Preencher dados

Inserir pessoas

INSERT INTO Person (id, name, birthday, country, city) VALUES
(1, 'Alex', '1990-01-01T00:00:00Z', 'USA', 'New York'),
(2, 'Lee', '1985-05-15T00:00:00Z', 'USA', 'San Francisco'),
(3, 'Dana', '1995-08-20T00:00:00Z', 'Canada', 'Vancouver'),
(4, 'Maria', '1992-04-15T00:00:00Z', 'USA', 'Chicago'),
(5, 'David', '1988-11-20T00:00:00Z', 'Canada', 'Toronto');

Inserir contas

INSERT INTO Account (id, create_time, is_blocked, nick_name) VALUES
(7, '2020-01-10T14:22:20.222Z', false, 'Vacation Fund'),
(16, '2020-01-28T01:55:09.206Z', true, 'Vacation Fund'),
(20, '2020-02-18T13:44:20.655Z', false, 'Rainy Day Fund'),
(25, '2023-01-15T10:00:00Z', false, 'Savings'),
(30, '2023-02-20T11:00:00Z', false, 'Checking');

INSERT INTO PersonOwnAccount (id, account_id, create_time) VALUES
(1, 7, '2020-01-10T14:22:20.222Z'),
(2, 16, '2020-01-28T01:55:09.206Z'),
(3, 20, '2020-02-18T13:44:20.655Z'),
(4, 25, '2023-01-15T10:00:00Z'),
(5, 30, '2023-02-20T11:00:00Z');

Adicionar transferências

INSERT INTO AccountTransferAccount (id, to_id, amount, create_time, order_number) VALUES
(7, 16, 300, '2024-02-28T10:00:00Z', 'ORD123'),
(7, 16, 100, '2024-02-29T11:00:00Z', 'ORD124'),
(16, 20, 300, '2024-02-29T12:00:00Z', 'ORD125'),
(20, 7, 500, '2024-02-29T13:00:00Z', 'ORD126'),
(20, 16, 200, '2024-02-29T14:00:00Z', 'ORD127'),
(7, 25, 150.75, '2024-03-01T12:00:00Z', 'ORD456'),
(25, 30, 200.00, '2024-03-02T14:30:00Z', 'ORD457'),
(30, 16, 50.25, '2024-03-03T16:00:00Z', 'ORD458');

3. Configurar a CLI do Gemini e o MCP do Spanner

O laboratório foi projetado para usar a CLI do Gemini como o principal agente para realizar a maioria das ações. A primeira etapa é configurar a CLI para trabalhar com o servidor MCP remoto do Spanner. Também é altamente recomendável usar a versão mais recente da CLI do Gemini e a versão mais recente do Gemini, como Gemini-3-pro ou Gemini-3-flash (atualmente em prévia).

Se você já tem a versão mais recente da CLI do Gemini e a configurou para usar os modelos mais recentes do Gemini, pule as próximas duas etapas e vá direto para a etapa 3.

Receber chave da API Gemini

Para usar os modelos mais recentes do Gemini na CLI Gemini, ela precisa ser configurada com uma autenticação de chave de API. Podemos receber a chave de API no Google AI Studio

  1. Acesse o Google AI Studio -> Receber chave de API no seu navegador.
  2. No lado direito da tela, clique no botão Create API key.
  3. Na janela pop-up, escolha seu projeto ou importe se ele não estiver visível.

4072657f24158cbe.png

  1. Crie a chave de API.
  2. Você pode copiar a chave usando o botão de cópia no lado direito.

a9a9a1bddb81ae21.png

A chave está preparada e agora podemos usá-la para a CLI do Gemini.

Configurar a CLI do Gemini

A CLI do Gemini pode ser configurada usando o arquivo de configurações ou de forma interativa com o comando /settings. Queremos que as configurações sejam preservadas no arquivo de configurações.

Primeiro, vamos criar um diretório para o projeto. Vamos chamar o diretório de projectspannermcp e mudar para ele usando os seguintes comandos.

mkdir ~/projectspannermcp
cd ~/projectspannermcp

No diretório, vamos criar um diretório para arquivos de configuração do Gemini e executar todos os nossos comandos. Por padrão, a CLI do Gemini usa um arquivo de configuração de escopo do usuário e extensões instaladas no diretório ~/.gemini. Mas vamos criar nossa própria configuração de escopo do projeto no diretório ~/projectspannermcp. Vamos começar criando o diretório e os arquivos de configuração.

mkdir ~/projectspannermcp/.gemini
touch ~/projectspannermcp/.gemini/settings.json

Em seguida, abra o arquivo ~/projectspannermcp/.gemini/settings.json usando o editor do Cloud Shell.

edit ~/projectspannermcp/.gemini/settings.json

Na janela do editor aberta, adicione a seguinte configuração.

{
  "general": {
    "preferredEditor": "vscode",
    "previewFeatures": true,
    "sessionRetention": {
      "enabled": true
    }
  },
  "ide": {
    "enabled": true,
    "hasSeenNudge": true
  },
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  },
  "ui": {
    "theme": "Default"
  },
  "tools": {
    "shell": {
      "enableInteractiveShell": false
    }
  }
}

Depois de editar o arquivo, use ctrl+s para salvar as mudanças e volte ao terminal clicando no botão Open Terminal.

b4d9fc5b7a8bc7b7.png

O arquivo settings.json acima define o tipo de autenticação da CLI do Gemini como "gemini-api-key", e você precisa fornecer a chave ao modelo. Para isso, crie um arquivo .env no diretório em que você quer trabalhar com a CLI do Gemini e armazene sua chave de API para autenticação da CLI do Gemini como uma variável de ambiente, que será selecionada quando você iniciar o IDE.

Vamos editar o arquivo usando o editor do Cloud Shell.

edit ~/projectspannermcp/.env

e armazene a chave de API criada na etapa "Receber chave da API Gemini" acima.

GEMINI_API_KEY= <YOUR_API_KEY>

Agora você pode voltar ao terminal e continuar. A próxima etapa é atualizar a CLI do Gemini para a versão mais recente. A versão no Google Cloud Shell ou no seu ambiente pode estar desatualizada e não funcionar corretamente com as configurações e os serviços do MCP mais recentes. Por isso, é importante atualizar e iniciar a CLI do Gemini. No terminal, execute o seguinte.

cd ~/projectspannermcp/
npm install -g @google/gemini-cli@latest

Agora você pode verificar a versão. Se você estiver trabalhando no Google Cloud Shell, lembre-se de que, a cada reinicialização, ele poderá voltar para a versão anterior. As mudanças feitas na CLI do Gemini não são permanentes no Cloud Shell.

gemini --version

Ela vai mostrar a versão mais recente da CLI do Gemini (versão 0.27 no momento em que o laboratório foi escrito). Confira a versão mais recente da CLI do Gemini aqui. Agora podemos iniciar e garantir que ele esteja usando o modelo mais recente do Gemini. Execute o comando a seguir na pasta do projeto para iniciar a CLI do Gemini.

gemini

Quando a CLI do Gemini for iniciada, você poderá verificar a versão e o modelo executando o comando /about na interface. Você vai receber algo como a imagem abaixo.

af2be742dd0a5bc1.png

Você pode ver que ele está usando o modelo mais recente do Gemini-3. As etapas abaixo que demonstram a consulta em linguagem natural exigem o uso do modelo Gemini-3.

Configurar a CLI do Gemini para usar o MCP do Spanner

Temos mais uma coisa para adicionar ao arquivo settings.json. Primeiro, saia da CLI do Gemini (pressione Ctrl+C duas vezes).

No mesmo settings.json acima, vamos adicionar o bit para configurar nosso servidor MCP do Spanner. Incluímos o settings.json completo abaixo. Observe o bit que começa com "mcpServers".

{
 "general": {
   "preferredEditor": "vscode",
   "previewFeatures": true,
   "sessionRetention": {
     "enabled": true
   }
 },
 "ide": {
   "enabled": true,
   "hasSeenNudge": true
 },
 "security": {
   "auth": {
     "selectedType": "gemini-api-key"
   }
 },
 "ui": {
   "theme": "Default"
 },
 "tools": {
   "shell": {
     "enableInteractiveShell": false
   }
 },
 "mcpServers": {
   "spanner": {
     "httpUrl": "https://spanner.googleapis.com/mcp",
     "authProviderType": "google_credentials",
     "oauth": {
       "scopes": ["https://www.googleapis.com/auth/spanner.admin",
                  "https://www.googleapis.com/auth/spanner.data"]
     },
     "timeout": 5000
   }
 },
 "mcp": {
   "allowed": [
     "spanner"
   ]
 }
}

Antes de continuar para a próxima etapa, faça a autenticação.

gcloud auth application-default login

Após a autenticação, inicie o gemini-cli novamente.

gemini

4. Gerar consultas multimodais, incluindo consultas focadas em gráficos

Vamos começar listando as instâncias do Spanner no projeto configurado.

"Liste todas as instâncias do Spanner no meu projeto <project1> (substitua pelo ID do seu projeto)"

Resposta:

The Spanner instances in your project are:
 [instance1]

"Liste todos os bancos de dados em <instance1> (substitua pela sua instância)"

Resposta:

The Spanner databases in [instance1] are:
  [database1]

Em seguida, vamos pedir ao Gemini para lembrar a instância/banco de dados em que você executou as instruções DDL e as instruções de inserção na seção de configuração do Spanner:

"Suponha que todas as consultas serão enviadas ao banco de dados <your-db> na instância <your-instance>, a menos que seja declarado o contrário"

NOTE: use a instância/o banco de dados em que você executou as instruções DDL e as instruções de inserção acima.

Depois de conectado, o modelo do Gemini entende o esquema do gráfico. Agora você pode executar travessias sofisticadas usando linguagem natural.

O modelo vai traduzir automaticamente para GQL (Graph Query Language):

Identificar estruturas de rede

"Descreva a estrutura do gráfico de propriedades "FinGraph". Quais são os rótulos de nós e arestas?"

Resposta:

  Node Labels
   * `Account`: Represents financial accounts.
       * Properties: id, create_time, is_blocked, nick_name
   * `Person`: Represents individuals.
       * Properties: id, name, birthday, country, city

  Edge Labels
   * `Transfers`: Represents a transfer between two Account nodes.
       * Source: Account
       * Destination: Account
       * Properties: id, to_id, amount, create_time, order_number
   * `Owns`: Represents a Person owning an Account.
       * Source: Person
       * Destination: Account
       * Properties: id, account_id, create_time

Detecção de fraudes e ciclos

"Encontre transferências circulares em que o dinheiro foi enviado da Conta A e devolvido para a Conta A em até três etapas."

Resposta:

The analysis confirms the following circular transfers where money returns to the originating account within 3 hops:

  3-Hop Cycles
  Money travels through two intermediate accounts before returning to the origin.
   * Account 16 (Involved in multiple 3-hop paths)
   * Account 20 (Involved in multiple 3-hop paths)
   * Account 7 (Involved in multiple 3-hop paths)

These accounts are participating in circular flow patterns of varying lengths.

Análise detalhada de relacionamento

"Identifique todas as pessoas que têm contas que enviaram mais de US $499 para contas de outras pessoas nos últimos 24 meses."

Resposta:

Dana is the only person who owns an account that has sent more than $499 to an account owned by a different person in the last 24 months.

(Specifically, her account sent exactly $500, which is the maximum transfer amount in the database).

Localização de caminhos

"Encontre o caminho mais curto de transferências entre o ID da conta 16 e o ID da conta 20."

Resposta:

The shortest path between Account 16 and Account 20 is 1 hop.

This means there is a direct transfer from Account 16 to Account 20.

5. Parabéns!

Parabéns por concluir o codelab.

O que aprendemos

Neste codelab, você aprendeu a configurar o gemini-cli com o servidor MCP do Spanner e a fazer consultas em linguagem natural nos dados do gráfico do Spanner para gerar insights. Confira um resumo dos principais marcos:

  • Infraestrutura gerenciada:ativamos o servidor MCP remoto do Spanner, eliminando a necessidade de proxies locais ou da caixa de ferramentas do MCP.
  • Integração de gráficos:configuramos um gráfico de propriedades do Spanner (FinGraph) com nós e arestas para representar relações complexas.
  • Ferramentas nativas:conectamos a CLI do Gemini diretamente ao endpoint gerenciado do Spanner usando um esquema de URI padrão.
  • SQL em linguagem natural e GQL:exercitou o servidor com comandos específicos do gráfico, permitindo que o LLM fizesse travessias de várias etapas e detecção de ciclos sem programação manual em SQL/GQL.
  • Prontidão empresarial:explicamos como o MCP gerenciado oferece um caminho escalonável e autenticado para os agentes de IA interagirem com dados operacionais.