MCP Reference: cloud-sql

Model Context Protocol（MCP）サーバーは、大規模言語モデル（LLM）または AI アプリケーションにコンテキスト、データ、機能を提供する外部サービスとの間のプロキシとして機能します。MCP サーバーは、AI アプリケーションをデータベースやウェブサービスなどの外部システムに接続し、そのレスポンスを AI アプリケーションが理解できる形式に変換します。

サーバーの設定

使用する前に、MCP サーバーを有効にして 認証を設定する必要があります。Google と Google Cloud のリモート MCP サーバーの使用方法については、Google Cloud MCP サーバーの概要をご覧ください。

MCP 用の Cloud SQL Admin API

サーバー エンドポイント

MCP サービス エンドポイントは、安全で標準化された接続を確立するために AI アプリケーション（MCP クライアントのホスト）が使用する MCP サーバーのネットワーク アドレスと通信インターフェース（通常は URL）です。これは、LLM がコンテキストをリクエストしたり、ツールを呼び出したり、リソースにアクセスしたりするための接続ポイントとなります。Google MCP エンドポイントをグローバルまたはリージョンにすることができます。

cloud-sql MCP サーバーには、次の MCP エンドポイントがあります。

  • https://sqladmin.googleapis.com/mcp

MCP ツール

MCP ツールは、現実世界でアクションを実行する目的で MCP サーバーが LLM または AI アプリケーションに対して公開する関数または実行可能な機能です。

cloud-sql MCP サーバーには次のツールがあります。

MCP ツール
list_instances プロジェクト内のすべての Cloud SQL インスタンスを一覧表示します。
get_instance Cloud SQL インスタンスの詳細を取得します。
create_instance

Cloud SQL インスタンスの作成を開始します。

  • このツールは、長時間実行オペレーションを返します。オペレーションが完了するまで、get_operation ツールを使用してステータスをポーリングします。
  • インスタンスの作成オペレーションには数分かかることがあります。コマンドライン ツールを使用して 30 秒間一時停止してから、ステータスを再確認します。
  • create_instance ツールを使用してインスタンスを作成したら、create_user ツールを使用して、現在プロジェクトにログインしているユーザーの IAM ユーザー アカウントを作成できます。
  • 重要: Private Service Connect または Private Service Access インスタンスを作成する場合は、ipv4_enabled を「false」に設定します。

  • data_api_access の値は、デフォルトで ALLOW_DATA_API に設定されています。この設定により、execute_sql ツールと executeSql API を使用して SQL ステートメントを実行できます。

特に指定しない限り、新しく作成されたインスタンスは開発環境のデフォルトのインスタンス構成を使用します。

開発環境のインスタンスのデフォルト構成は次のとおりです。

{
  "tier": "db-perf-optimized-N-2",
  "data_disk_size_gb": 100,
  "region": "us-central1",
  "database_version": "POSTGRES_18",
  "edition": "ENTERPRISE_PLUS",
  "availability_type": "ZONAL",
  "tags": [{"environment": "dev"}]
}

本番環境のインスタンスには、次の構成をおすすめします。

{
  "tier": "db-perf-optimized-N-8",
  "data_disk_size_gb": 250,
  "region": "us-central1",
  "database_version": "POSTGRES_18",
  "edition": "ENTERPRISE_PLUS",
  "availability_type": "REGIONAL",
  "tags": [{"environment": "prod"}]
}

SQL Server には、次のインスタンス構成をおすすめします。

{
  "tier": "db-perf-optimized-N-8",
  "data_disk_size_gb": 250,
  "region": "us-central1",
  "database_version": "SQLSERVER_2022_STANDARD",
  "edition": "ENTERPRISE",
  "availability_type": "REGIONAL",
  "tags": [{"environment": "prod"}]
}
execute_sql

Cloud SQL インスタンスで、データ定義言語（DDL）、データ制御言語（DCL）、データクエリ言語（DQL）、データ操作言語（DML）のステートメントなど、有効な SQL ステートメントを実行します。

execute_sql ツールをサポートするには、Cloud SQL インスタンスが次の要件を満たしている必要があります。

  • data_api_access の値は ALLOW_DATA_API に設定する必要があります。
  • 組み込みユーザーの場合は、password_secret_version を設定する必要があります。
  • それ以外の場合、IAM ユーザーの場合は、MySQL インスタンスでデータベース フラグ cloudsql_iam_authentication を on に設定する必要があります。PostgreSQL インスタンスの場合は、データベース フラグ cloudsql.iam_authentication を on に設定する必要があります。
  • create_instance ツールを使用してインスタンスを作成したら、create_user ツールを使用して、現在プロジェクトにログインしているユーザーの IAM ユーザー アカウントを作成できます。

execute_sql ツールには次の制限があります。

  • SQL ステートメントが 10 MB を超えるレスポンスを返すと、レスポンスは切り捨てられます。
  • execute_sql ツールのデフォルトのタイムアウトは 30 秒です。クエリの実行時間が 30 秒を超えると、ツールは DEADLINE_EXCEEDED エラーを返します。
  • execute_sql ツールは SQL Server ではサポートされていません。

「IAM 認証がインスタンスで有効になっていません」などのエラーが表示された場合は、get_instance ツールを使用して、インスタンスの IAM データベース認証フラグの値を確認できます。

「インスタンスでは executeSql を使用してこのインスタンスにアクセスできません」などのエラーが表示された場合は、get_instance ツールを使用して data_api_access 設定を確認できます。

認証エラーが発生した場合:

  1. list_users ツールを使用して、現在ログインしているユーザー アカウントがインスタンスの IAM ユーザーとして存在するかどうかを確認します。
  2. IAM ユーザー アカウントが存在しない場合は、create_user ツールを使用して、ログインしているユーザーの IAM ユーザー アカウントを作成します。
  3. 現在ログインしているユーザーに適切なデータベース ユーザーロールがない場合は、update_user ツールを使用して、ユーザーにデータベース ロールを付与できます。たとえば、cloudsqlsuperuser ロールを使用すると、IAM ユーザーに必要な権限を多数付与できます。

  4. 現在ログインしているユーザーに、プロジェクトに割り当てられた正しい IAM 権限があるかどうかを確認します。gcloud projects get-iam-policy [PROJECT_ID] コマンドを使用して、ユーザーにプロジェクトに割り当てられた適切な IAM ロールまたは権限があるかどうかを確認できます。

    • 自動 IAM データベース認証を行うには、ユーザーに cloudsql.instance.login 権限が必要です。
    • SQL ステートメントを実行するには、ユーザーに cloudsql.instances.executeSql 権限が必要です。execute_sql ツールまたは executeSql API を使用します。
    • 必要な権限を含む一般的な IAM ロール: Cloud SQL インスタンス ユーザー（roles/cloudsql.instanceUser）または Cloud SQL 管理者（roles/cloudsql.admin）

ExecuteSqlResponse を受信したら、レスポンスの本文内の message フィールドと status フィールドを必ず確認してください。HTTP ステータス コードが成功しても、すべての SQL ステートメントが完全に成功するとは限りません。SQL ステートメントの実行中に部分的なエラーや警告が発生した場合は、message フィールドと status フィールドに示されます。
execute_sql_readonly

Cloud SQL インスタンスで有効な読み取り専用 SQL ステートメントを実行します。

execute_sql_readonly ツールをサポートするには、Cloud SQL インスタンスが次の要件を満たしている必要があります。

  • data_api_access の値は ALLOW_DATA_API に設定する必要があります。
  • MySQL インスタンスの場合は、データベース フラグ cloudsql_iam_authentication を on に設定する必要があります。PostgreSQL インスタンスの場合は、データベース フラグ cloudsql.iam_authentication を on に設定する必要があります。
  • execute_sql_readonly ツールを呼び出すには、IAM ユーザー アカウントまたは IAM サービス アカウント（CLOUD_IAM_USER または CLOUD_IAM_SERVICE_ACCOUNT）が必要です。このツールは、IAM データベース認証でログインしたデータベース ユーザーの権限を使用して SQL ステートメントを実行します。

create_instance ツールを使用してインスタンスを作成したら、create_user ツールを使用して、現在プロジェクトにログインしているユーザーの IAM ユーザー アカウントを作成できます。

execute_sql_readonly ツールには次の制限があります。

  • SQL ステートメントが 10 MB を超えるレスポンスを返すと、レスポンスは切り捨てられます。
  • このツールのデフォルトのタイムアウトは 30 秒です。 クエリの実行時間が 30 秒を超えると、ツールは DEADLINE_EXCEEDED エラーを返します。
  • このツールは SQL Server ではサポートされていません。

「IAM 認証がインスタンスで有効になっていません」などのエラーが表示された場合は、get_instance ツールを使用して、インスタンスの IAM データベース認証フラグの値を確認できます。

「インスタンスでは executeSql を使用してこのインスタンスにアクセスできません」などのエラーが表示された場合は、get_instance ツールを使用して data_api_access 設定を確認できます。

認証エラーが発生した場合:

  1. list_users ツールを使用して、現在ログインしているユーザー アカウントがインスタンスの IAM ユーザーとして存在するかどうかを確認します。
  2. IAM ユーザー アカウントが存在しない場合は、create_user ツールを使用して、ログインしているユーザーの IAM ユーザー アカウントを作成します。
  3. 現在ログインしているユーザーに適切なデータベース ユーザーロールがない場合は、update_user ツールを使用して、ユーザーにデータベース ロールを付与できます。たとえば、cloudsqlsuperuser ロールを使用すると、IAM ユーザーに必要な権限を多数付与できます。

  4. 現在ログインしているユーザーに、プロジェクトに割り当てられた正しい IAM 権限があるかどうかを確認します。gcloud projects get-iam-policy [PROJECT_ID] コマンドを使用して、ユーザーにプロジェクトに割り当てられた適切な IAM ロールまたは権限があるかどうかを確認できます。

    • 自動 IAM データベース認証を行うには、ユーザーに cloudsql.instance.login 権限が必要です。
    • SQL ステートメントを実行するには、ユーザーに cloudsql.instances.executeSql 権限が必要です。execute_sql_readonly ツールまたは executeSql API を使用します。
    • 必要な権限を含む一般的な IAM ロール: Cloud SQL インスタンス ユーザー（roles/cloudsql.instanceUser）または Cloud SQL 管理者（roles/cloudsql.admin）

ExecuteSqlResponse を受信したら、レスポンスの本文内の message フィールドと status フィールドを必ず確認してください。HTTP ステータス コードが成功しても、すべての SQL ステートメントが完全に成功するとは限りません。SQL ステートメントの実行中に部分的なエラーや警告が発生した場合は、message フィールドと status フィールドに示されます。
get_operation 長時間実行オペレーションのステータスを取得します。長時間実行オペレーションが完了するまでに数分かかることがあります。オペレーションに時間がかかる場合は、コマンドライン ツールを使用して 30 秒間一時停止してから、オペレーションのステータスを再確認します。
create_user

Cloud SQL インスタンスのデータベース ユーザーを作成します。

  • このツールは、長時間実行オペレーションを返します。オペレーションが完了するまで、get_operation ツールを使用してステータスをポーリングします。
  • create_user ツールを使用する場合は、ユーザーのタイプ（CLOUD_IAM_USER、CLOUD_IAM_SERVICE_ACCOUNT、BUILT_IN）を指定します。
  • リクエストで他のデータベース ロールを明示的に指定しない限り、新しく作成されたユーザーにはデフォルトで cloudsqlsuperuser ロールが割り当てられます。
  • 現在ログインしている IAM ユーザーの場合は、新しく作成したユーザーを execute_sql ツールで使用できます。execute_sql ツールは、IAM データベース認証を使用してログインしたデータベース ユーザーの権限を使用して SQL ステートメントを実行します。

create_user ツールには次の制限があります。

  • パスワード付きの組み込みユーザーを作成するには、password_secret_version フィールドを使用して、Google Cloud Secret Manager を使用してパスワードを指定します。password_secret_version の値は、シークレット バージョンのリソース名（projects/12345/locations/us-central1/secrets/my-password-secret/versions/1 や projects/12345/locations/us-central1/secrets/my-password-secret/versions/latest など）にする必要があります。呼び出し元には、シークレット バージョンに対する secretmanager.secretVersions.access 権限が必要です。
  • create_user ツールは、SQL Server のユーザーの作成をサポートしていません。

PostgreSQL で IAM ユーザーを作成するには:

  • データベース ユーザー名は、IAM ユーザーのメールアドレスで、すべて小文字にする必要があります。 たとえば、PostgreSQL IAM ユーザー example-user@example.com のユーザーを作成するには、次のリクエストを使用します。
{
  "name": "example-user@example.com",
  "type": "CLOUD_IAM_USER",
  "instance":"test-instance",
  "project": "test-project"
}

IAM ユーザー用に作成されたデータベース ユーザー名は example-user@example.com です。

PostgreSQL で IAM サービス アカウントを作成するには:

  • アカウントの完全なメールアドレスが service-account-name@project-id.iam.gserviceaccount.com であっても、データベース ユーザー名は .gserviceaccount.com サフィックスなしで作成する必要があります。たとえば、PostgreSQL の IAM サービス アカウントを作成するには、次のリクエスト形式を使用します。
{
   "name": "test@test-project.iam",
   "type": "CLOUD_IAM_SERVICE_ACCOUNT",
   "instance": "test-instance",
   "project": "test-project"
}

IAM サービス アカウント用に作成されたデータベース ユーザー名は test@test-project.iam です。

MySQL で IAM ユーザーまたは IAM サービス アカウントを作成するには:

  • Cloud SQL for MySQL がユーザー名を格納するときに、ユーザーまたはサービス アカウントのメールアドレスから @ とドメイン名が切り捨てられます。たとえば、example-user@example.com は example-user になります。
  • このため、同じユーザー名で異なるドメイン名の 2 つの IAM ユーザーまたはサービス アカウントを同じ Cloud SQL インスタンスに追加することはできません。
  • たとえば、MySQL IAM ユーザー example-user@example.com のユーザーを作成するには、次のリクエストを使用します。
{
   "name": "example-user@example.com",
   "type": "CLOUD_IAM_USER",
   "instance": "test-instance",
   "project": "test-project"
}

IAM ユーザー用に作成されたデータベース ユーザー名は example-user です。

  • たとえば、MySQL IAM サービス アカウント service-account-name@project-id.iam.gserviceaccount.com を作成するには、次のリクエストを使用します。
{
   "name": "service-account-name@project-id.iam.gserviceaccount.com",
   "type": "CLOUD_IAM_SERVICE_ACCOUNT",
   "instance": "test-instance",
   "project": "test-project"
}

IAM サービス アカウント用に作成されたデータベース ユーザー名は service-account-name です。
update_user

Cloud SQL インスタンスのデータベース ユーザーを更新します。update_user の一般的なユースケースは、ユーザーに cloudsqlsuperuser ロールを付与することです。これにより、ユーザーに必要な権限を多数付与できます。

このツールは、データベース ロールを割り当てるためにユーザーを更新する場合にのみサポートされます。

  • このツールは、長時間実行オペレーションを返します。オペレーションが完了するまで、get_operation ツールを使用してステータスをポーリングします。
  • update_user ツールを呼び出す前に、list_users ツールを使用して、ユーザータイプなど、ユーザーの既存の構成を必ず確認してください。
  • MySQL の特殊なケースとして、list_users ツールが iamEmail フィールドに完全なメールアドレス（{name=test-account, iamEmail=test-account@project-id.iam.gserviceaccount.com} など）を返す場合は、update_user リクエストで、ツールのリクエストの name フィールドの iamEmail フィールドに完全なメールアドレスを使用します。例: name=test-account@project-id.iam.gserviceaccount.com。

ユーザーロールを更新するためのキーパラメータ:

  • database_roles: ユーザーに割り当てるデータベース ロールのリスト。
  • revokeExistingRoles: 既存のロールの処理方法を制御するブール値フィールド（デフォルト: false）。

ロールの更新の仕組み:

  1. revokeExistingRoles が true の場合:

    • ユーザーに付与されているが、指定された database_roles リストに含まれていない既存のロールはすべて取り消されます。
    • 取り消しはシステム以外のロールにのみ適用されます。cloudsqliamuser などのシステムロールは取り消されません。
    • ユーザーがまだ持っていない database_roles リスト内のロールはすべて付与されます。
    • database_roles が空の場合、既存のシステム以外のロールはすべて取り消されます。

  2. revokeExistingRoles が false の場合（デフォルト）:

    • ユーザーがまだ持っていない database_roles リスト内のロールはすべて付与されます。
    • database_roles リストに含まれていない既存のロールは保持されます。
    • database_roles が空の場合、ユーザーのロールは変更されません。

例:

  • 既存のロール: [roleA, roleB]

    • リクエスト: database_roles: [roleB, roleC], revokeExistingRoles: true
    • 結果: roleA を取り消し、roleC を付与します。ユーザーロールは [roleB, roleC] になります。
    • リクエスト: database_roles: [roleB, roleC], revokeExistingRoles: false
    • 結果: roleC を付与します。ユーザーロールは [roleA, roleB, roleC] になります。
    • リクエスト: database_roles: [], revokeExistingRoles: true
    • 結果: roleA を取り消し、roleB を取り消します。ユーザーロールは [] になります。
    • リクエスト: database_roles: [], revokeExistingRoles: false
    • 結果: 変更はありません。ユーザーロールは [roleA, roleB] のままです。
clone_instance

Cloud SQL インスタンスを、ソース インスタンスのクローンとして作成します。

  • このツールは、長時間実行オペレーションを返します。オペレーションが完了するまで、get_operation ツールを使用してステータスをポーリングします。
  • クローン オペレーションには数分かかることがあります。コマンドライン ツールを使用して 30 秒間一時停止してから、ステータスを再確認します。
update_instance

Cloud SQL インスタンスの構成設定を部分的に更新します。

  • このツールは、長時間実行オペレーションを返します。オペレーションが完了するまで、get_operation ツールを使用してステータスをポーリングします。
  • エディションのアップグレードやインスタンス ティアの変更など、一部の更新オペレーションでは、インスタンスが再起動し、ダウンタイムが発生する可能性があります。このようなオペレーションを行う前に、ユーザーに確認してください。
list_users Cloud SQL インスタンスのすべてのデータベース ユーザーを一覧表示します。
create_backup Cloud SQL インスタンスでバックアップを作成します。リクエストには必ずプロジェクト フィールドとインスタンス フィールドを入力してください。バックアップのロケーション（リージョン）と説明を指定することもできます。その場合は、対応するリクエスト フィールドにも入力する必要があります。
restore_backup

Cloud SQL インスタンスにバックアップを復元します。

リクエストで target_instance と target_project を指定して入力する必要があります。

バックアップ識別子は、次の方法で指定できます。

  1. backup_run_id（整数）。
  2. projects/{project-id}/backups/{backup-uid} 形式のバックアップ URI。
  3. projects/{project-id}/locations/{location}/backupVaults/{backupvault}/dataSources/{datasource}/backups/{backup-uid} 形式のバックアップ URI。

識別子を使用して、リクエストの backup_id フィールドに入力します。

リクエストで source_project を入力する必要があります。識別子が backup_run_id の場合は、source_project が指定されます。識別子がバックアップ URI の場合は、URI から source_project を抽出する必要があります。抽出した source_project を target_project と混同しないでください。target_project は別の方法で指定されます。

また、識別子が backup_run_id の場合は、source_instance を指定してリクエストに入力する必要があります。

復元する前にインスタンスを作成しないでください。復元時に必要に応じてインスタンスが作成されます。

復元を実行する前に、ユーザーにパラメータを確認してください。
import_data

Cloud SQL インスタンスにデータをインポートします。

ファイルが gs:// で始まらない場合は、ファイルがローカルに保存されていると見なされます。ファイルがローカルにある場合は、実際の import_data 呼び出しを行う前に、ファイルを Cloud Storage にアップロードする必要があります。ファイルを Cloud Storage にアップロードするには、gcloud コマンドまたは gsutil コマンドを使用します。

ファイルを Cloud Storage にアップロードする前に、既存のバケットを使用するか、指定されたプロジェクトに新しいバケットを作成するかを検討してください。

ファイルが Cloud Storage にアップロードされたら、インスタンス サービス アカウントに、Cloud Storage バケットからアップロードされたファイルを読み取るための十分な権限が必要です。

これは、次のようにして実現できます。

  1. get_instance ツールを使用して、インスタンス サービス アカウントのメールアドレスを取得します。ツールの出力から、serviceAccountEmailAddress フィールドの値を取得します。
  2. 指定された Cloud Storage バケットに対する storage.objectAdmin ロールをインスタンス サービス アカウントに付与します。gcloud storage buckets add-iam-policy-binding などのコマンドまたは Cloud Storage API へのリクエストを使用します。ロールが付与され、権限が Cloud Storage のサービス アカウントに伝播されるまでに 2 ～ 7 分以上かかることがあります。IAM ポリシーの更新後に権限エラーが発生した場合は、数分待ってからもう一度お試しください。

権限が付与されたら、データをインポートできます。省略可能なパラメータは空のままにして、システムのデフォルトを使用することをおすすめします。通常、ファイルタイプはファイル拡張子で判断できます。たとえば、ファイルが SQL ファイルの場合は .sql、CSV ファイルの場合は .csv です。

MySQL の SQL importContext の例を次に示します。

{
  "uri": "gs://sample-gcs-bucket/sample-file.sql",
  "kind": "sql#importContext",
  "fileType": "SQL"
}

データベース名は SQL ファイルに存在することが想定されているため、MySQL には database パラメータはありません。URI は 1 つのみ指定します。importContext 以外のフィールドは必要ありません。

PostgreSQL の場合は、database フィールドが必要です。次に、database フィールドを指定した PostgreSQL importContext の例を示します。

{
  "uri": "gs://sample-gcs-bucket/sample-file.sql",
  "kind": "sql#importContext",
  "fileType": "SQL",
  "database": "sample-db"
}

import_data ツールは、長時間実行オペレーションを返します。オペレーションが完了するまで、get_operation ツールを使用してステータスをポーリングします。
postgres_upgrade_precheck

Cloud SQL for PostgreSQL インスタンスが、指定されたターゲット バージョンへのメジャー バージョン アップグレードの準備ができているかどうかを確認します。

リクエストで target_database_version を指定する必要があります（例: POSTGRES_15）。

このツールは、実際のアップグレードを試みる前に潜在的な問題を特定し、失敗やダウンタイムのリスクを軽減します。

このツールは PostgreSQL プライマリ インスタンスでのみサポートされており、リードレプリカでは実行されません。

通常、事前チェックでは次の点が評価されます。

  • ターゲット バージョンとのデータベース スキーマの互換性。
  • Cloud SQL の制限事項とサポートされていない機能。
  • インスタンス リソースの制約（リレーションの数など）。
  • 現在のデータベース設定と拡張機能の互換性。
  • インスタンスの全体的な健全性と準備状況。

このツールは、長時間実行オペレーションを返します。この呼び出しで返されたオペレーション名を使用して、get_operation ツールでステータスをポーリングします。

重要: オペレーションのステータスが DONE になると、詳細な事前チェックの結果が Operation リソース内で確認できます。get_operation からのレスポンスを確認する必要があります。結果は pre_check_major_version_upgrade_context.pre_check_response フィールドにあります。

結果は構造化されており、次のことを示します。

  • 情報: 全般情報。
  • 警告: アップグレードはブロックしないが、確認する必要がある潜在的な問題。
  • エラー: アップグレードを試みる前に解決する必要がある重大な問題。

各検出結果には、メッセージと必要なアクションを含める必要があります。メジャー バージョン アップグレードに進む前に、報告された問題を解決することが重要です。pre_check_response が空または存在しない場合は、事前チェックで問題が特定されなかったことを示します。

この事前チェックを実行しても、インスタンスの可用性に影響はありません。

MCP ツールの仕様を取得する

MCP サーバー内のすべてのツールの MCP ツール仕様を取得するには、tools/list メソッドを使用します。次の例は、curl を使用して、MCP サーバー内で現在使用可能なすべてのツールとその仕様を一覧表示する方法を示しています。

Curl リクエスト 
                      curl --location 'https://sqladmin.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
    "method": "tools/list",
    "jsonrpc": "2.0",
    "id": 1
}'