Claude Media
Claude CodeでSpanner MCPサーバーに接続する手順 — OAuthとIAMロール
Claude CodeMCPClaude連携チュートリアル

Claude CodeでSpanner MCPサーバーに接続する手順 — OAuthとIAMロール

Cloud SpannerのリモートMCPサーバーはAPIキー非対応で、OAuthとIAMで認可します。Claude Codeでの登録コマンド、必要なロール、リダイレクトURIの落とし穴を解説します。

読了目安 約13分

Cloud SpannerにはGoogle Cloudが運営するリモートMCPサーバーがあり、エンドポイントはhttps://spanner.googleapis.com/mcpです。Claude Codeからはclaude mcp add --transport httpで登録できますが、つまずきやすいのは認証です。このサーバーはAPIキーを受け付けず、OAuth 2.0とIAMだけで認可します。

先に結論を表にします。

項目内容
エンドポイント内容https://spanner.googleapis.com/mcp
トランスポート内容Streamable HTTP
認証内容OAuth 2.0 + IAM(APIキーは非対応)
有効化内容Spanner APIを有効にすると使える
必要なロール内容roles/mcp.toolUser、roles/oauthconfig.editor、roles/spanner.admin
OAuthスコープ内容spanner.admin、spanner.data の2種類

Spanner MCPサーバーとは — 管理とSQL実行を担うリモートサーバー

Spanner MCPサーバーは、Spannerのインスタンスやデータベースの作成・管理・クエリを、AIアプリケーションから呼べるようにするサーバーです。Google Cloud側のインフラで動き、HTTPのエンドポイントとして公開されます。手元でプロセスを起動するローカル型とは違い、npxなどで何かをインストールする必要はありません。

ローカル型を使いたい場合は、Spanner向けのMCP Toolbox for Databasesが別にあります。リモート型は「Spanner APIを有効にした時点で使える」ので、導入の手間は認証の設定に集中します。ローカルとリモートの選び方はローカルMCPとリモートMCPの違いで比べています。

Spannerには、このサーバーとは別に「Database Insights」用のリモートサーバーもあります。性能やシステムメトリクスの分析向けで、インスタンスやデータベースの作成・SQL実行を担うのは本記事のSpannerサーバーです。

接続前に必要なもの — API・ロール・OAuthクライアント

Claude Codeのコマンドを打つ前に、Google Cloud側で3つ整えます。

手順

接続前に済ませる3つの準備

  1. 1

    プロジェクトと課金の確認

    対象のGoogle Cloudプロジェクトで課金が有効になっていることを確認します。Spanner APIは、新しいプロジェクトなら自動で有効です。既存プロジェクトで無効なら、有効化にserviceusage.services.enableの権限が要ります。

  2. 2

    IAMロールの付与

    MCPツールの呼び出しにroles/mcp.toolUser、OAuthクライアントの作成にroles/oauthconfig.editor、Spannerのツールの実行にroles/spanner.adminが必要です。ロールは接続するプロジェクトに付けます。

  3. 3

    OAuthクライアントの作成

    Google Cloudコンソールの「Google Auth Platform」から、アプリケーションタイプ「ウェブ アプリケーション」でクライアントを作ります。作成後に表示されるシークレットは一度しかコピーできません。失った場合は削除して作り直します。

roles/spanner.adminに含まれる権限は、インスタンスの作成(spanner.instances.create)やデータベースの書き込み(spanner.databases.write)まで含みます。つまり、このロールで接続したエージェントは、プロンプト次第でインスタンスを作れる立場になります。ドキュメントには、カスタムロールや別の事前定義ロールでも必要な権限を満たせると書かれています。読み取りだけ試したいなら、まず権限を絞ったロールから試す手があります。

認証主体についても指定があります。エージェント用に別のIDを作り、アクセスを個別に制御・監視することが推奨されています。自分のユーザー認証でつなぐと、操作は自分の名義で行われます。IAM側でMCP経由の利用を絞る方法はGoogle CloudのMCPサーバーをIAMで権限制御するにまとめています。

Claude Codeに登録する — claude mcp addの書き方

Spannerのドキュメントにクライアント別の手順があるのは、Gemini CLI・Claude.ai・ChatGPTの3つです。Claude Codeの専用手順は載っていません。そのため、Spannerの接続情報とClaude Codeのclaude mcp addの仕様を組み合わせて書くことになります。

Claude Codeへ渡す値は、汎用クライアント向けの案内にある次の4点です。

  • サーバーURL: https://spanner.googleapis.com/mcp
  • トランスポート: Streamable HTTP(Claude Codeでは--transport http)
  • 認証: OAuthクライアントIDとシークレット
  • スコープ: 使いたい範囲のOAuthスコープ

Claude CodeのMCP設定には、動的クライアント登録に対応しないサーバー向けに、事前に作ったOAuthクライアントを渡す仕組みがあります。--client-idでIDを渡し、--client-secretを付けるとシークレットをマスク入力で聞かれます。コールバックのポートは--callback-portで固定できます。

claude mcp add --transport http \
  --client-id YOUR_CLIENT_ID --client-secret --callback-port 8080 \
  spanner https://spanner.googleapis.com/mcp

シークレットは追加時にしか設定できません。後から変える場合はclaude mcp remove spannerで消し、同じスコープで入れ直します。保存先は、macOSならキーチェーン、それ以外は認証情報ファイルで、設定ファイルには書かれません。

JSONで書きたい場合はclaude mcp add-jsonを使います。スコープを絞るoauth.scopesは、スペース区切りの1つの文字列です。

claude mcp add-json spanner \
  '{"type":"http","url":"https://spanner.googleapis.com/mcp","oauth":{"clientId":"YOUR_CLIENT_ID","callbackPort":8080,"scopes":"https://www.googleapis.com/auth/spanner.data"}}' \
  --client-secret

Claude Codeのoauth設定の書式に、Spannerのスコープ名を当てはめた形です。spanner.dataを選んだのは「データの閲覧と管理」の範囲だからで、インスタンスの作成のような管理系のツールにはspanner.adminが関わるはずです。ただし、どのツールにどちらのスコープが要るかの対応表はドキュメントにありません。管理系のツールで権限不足になったら、スコープにspanner.adminを足して認証し直します。

登録できたら、次の流れで確認します。

手順

登録後の確認

  1. 1

    状態の確認

    claude mcp get spannerで、OAuthの認証情報が設定されているかを確認できます。claude mcp listの表示が! Needs authenticationなら、まだサインインが済んでいません。

  2. 2

    ブラウザでサインイン

    Claude Codeのセッション内で/mcpを開き、spannerを選んでブラウザのログインを進めます。

  3. 3

    ツールの確認

    サインイン後、/mcpでツールの一覧が出ることを確認します。

Spannerのドキュメントにはもう1つ、Gemini CLIの例にだけx-goog-user-projectヘッダーでプロジェクトIDを渡す設定があります。このヘッダーがClaude Codeでも必要かどうかは、ページに記載がありません。必要になった場合は、claude mcp addの--header "x-goog-user-project: PROJECT_ID"で付けられます。

リダイレクトURIの食い違い — ここが最初の落とし穴

落とし穴

Googleの案内とClaude Codeのコールバックが一致しない

Google側の案内(「Claude Code」の見出し)では、リダイレクトURIにhttps://claude.ai/api/mcp/auth_callbackを登録する手順になっています。この手順は、claude.aiのカスタムコネクタ用です。一方、Claude Codeのclaude mcp addで--client-idを使う場合のサインインは、http://localhost:PORT/callbackの形のローカルURLにコールバックされます。

Spannerのページには、さらに「カスタムのリダイレクトURIはサポートされない」とも書かれています。Spannerのページには、localhostのURLをウェブアプリのクライアントに登録できるかの記載がありません。登録を試してエラーになる場合は、次の節の別ルートに切り替えます。

Claude Code側では、固定ポートを使うなら--callback-port 8080と、クライアント側に登録するhttp://localhost:8080/callbackを揃える必要があります。OAuthクライアントの作成画面で拒否されたときは、ここが原因として最初に疑えます。

うまくいかないときの別ルート — claude.aiのカスタムコネクタ

Google側の手順どおりに進めるなら、claude.aiでカスタムコネクタを作る方法があります。claude.aiでSpanner MCPサーバーを使えるのは、Enterprise・Pro・Max・Teamのプランです。

手順

claude.aiのカスタムコネクタで接続する

  1. 1

    OAuthクライアントの作成

    アプリケーションタイプは「ウェブ アプリケーション」、リダイレクトURIはhttps://claude.ai/api/mcp/auth_callbackです。

  2. 2

    コネクタの追加

    Pro・Maxなら「設定 > コネクタ」、Enterprise・Teamなら「管理者設定 > コネクタ」で「カスタムコネクタを追加」を選びます。サーバーURLにhttps://spanner.googleapis.com/mcpを入れます。

  3. 3

    認証情報の入力

    詳細設定にOAuthクライアントIDを入れます。クライアントシークレットの入力欄はPro・Maxのプランだけにあります。

追加後はツールメニューでコネクタを有効にします。Claude Codeはclaude.aiのコネクタを取り込める仕組みを持っていますが、claude.aiのアカウントでログインしている場合に限られます。その条件と取り込みの流れはClaude CodeのMCP設定ガイドで確認してください。

使えるツールと、書き込みが起きる場所

Gemini CLIの手順に載っている/mcpの出力例では、Spannerサーバーのツールは次の10個です。

分類ツール
参照ツールlist_instances、get_instance、list_databases、get_database_ddl、get_operation
作成ツールcreate_instance、create_database
SQLと書き込みツールcreate_session、execute_sql、commit

ページの別の箇所には、リクエストタグの表にexecute_sql_readonlyが登場します。上の10個の出力例には含まれないツール名なので、読み取り専用のSQL実行ツールの有無は、接続後に/mcpで見るのが確実です。tools/listは認証なしで呼べるため、接続前にcurlで調べることもできます。

curl -X POST https://spanner.googleapis.com/TOOLSET_ENDPOINT \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/list' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

これはドキュメントの例を短くした形です。例ではparamsに_metaとしてプロトコルのバージョンやクライアントの機能も入れています。TOOLSET_ENDPOINTはサービス名の後ろのパスで、Spannerならmcp/toolset-nameのような形と説明されています。

プロトコルのバージョン2026-07-28では、MCPが「ステートレス」に変わっています。initializeのやり取りやMcp-Session-Idが不要になり、各リクエストが必要な情報をヘッダーか_metaに持ちます。curlで叩くときにヘッダーが多いのはそのためです。

データの書き込みはcreate_session、execute_sql、commitの組み合わせで行われます。公式の例では、インスタンスの作成からテーブルの作成、サンプルデータの挿入までを、プロンプト1つで進める流れが挙げられています。execute_sqlとcommitで実行したクエリには、それぞれmcp_execute_sqlとmcp_commitのリクエストタグが自動で付きます。Spannerの監査やトラブルシューティングで、MCP経由の操作を見分ける手がかりになります。

使い方の例として、ドキュメントには次のようなプロンプトがあります。

  • 「us-central1のリージョン構成で、Spannerインスタンスを作り、在庫管理のデータベースにサンプル商品を5件入れて」(開発用)
  • 「現在のプロジェクトのSpannerインスタンスを一覧して」「現在のデータベースのスキーマを見せて」(運用の確認用)

前者は課金されるリソースを作る操作です。試すなら、使い捨てのプロジェクトで行うのが安全です。ドキュメントも、手順で作ったリソースを残さないなら、新しいプロジェクトを作って後で削除するよう案内しています。

安全策 — Model ArmorとIAMポリシー

SpannerのMCPサーバーには、任意で使える安全策が2つあります。

Model Armorは、プロンプトとレスポンスを検査するGoogle Cloudのサービスです。プロジェクトの「フロア設定」でMCPのサニタイズを有効にすると、そのプロジェクトのMCPツール呼び出しとレスポンスに同じフィルタがかかります。ドキュメントの例はINSPECT_AND_BLOCK(検査して、一致したら遮断)です。注意点が3つあります。

  • ロギングを有効にすると、ペイロード全体が記録され、機密情報がログに残る可能性がある
  • Model Armorが対応しないリージョンでMCPを使うと、データレジデンシーの要件を満たさなくなる場合がある
  • フロア設定はVertex AIなど他の連携サービスにも効く

自然言語を運ばないMCP通信では、プロンプトインジェクションとジェイルブレイクのフィルタは有効にしない、という注意もあります。SQLなど自然言語でないデータが中心の通信では、この2つのフィルタは外しておく構成です。

IAMのポリシーでは、主体・ツールの読み取り専用属性・サービス名やツール名・OAuthクライアントIDで、許可と拒否を組めます。「書き込み系ツールだけを禁止する」といった運用が可能で、書き方は前述のIAMで権限制御する記事の例をそのまま流用できます。

試す順番の目安

Spannerの課金は、インスタンスを作った時点から発生します。接続の確認だけなら、書き込みをしない次の順で進めると、想定外のリソースが増えません。

  1. list_instancesなど参照系のツールだけを使う
  2. spanner.dataのスコープと、権限を絞ったロールで、execute_sqlのSELECTを試す
  3. 作成系は、使い捨てのプロジェクトで試す

ほかのGoogle Cloud製品のMCPをClaude Codeに載せる手順は、Claude BigQuery連携が同じ型で書かれています。認証の仕組みを掘り下げるなら、リモートMCPのOAuth認証が401から始まる流れを説明しています。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →