Learn how to use the BigQuery Migration Service MCP server

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms, and the Additional Terms for Generative AI Preview Products. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

This document shows you how to use the BigQuery remote Model Context Protocol (MCP) server to connect with AI applications including Gemini CLI, ChatGPT, Claude, and custom applications you are developing. You can BigQuery Migration Service Model Context Protocol (MCP) server to perform tasks such as translating SQL queries into GoogleSQL syntax, generating DDL statements from SQL input queries, and getting explanations of SQL translations..

The BigQuery remote MCP server is enabled when you enable the BigQuery API.

Model Context Protocol (MCP) standardizes how large language models (LLMs) and AI applications or agents connect to outside data sources. MCP servers let you use their tools, resources, and prompts to take actions and get updated data from their backend service.

Local MCP servers typically run on your local machine and use the standard input and output streams (stdio) for communication between services on the same device. MCP servers run on the service's infrastructure and offer an HTTPS endpoint to AI applications for communication between the AI MCP client and the MCP server. For more information on MCP architecture, see MCP architecture.

Google and Google Cloud MCP servers have the following features and benefits:

• Simplified, centralized discovery
• Managed global or regional HTTPS endpoints
• Fine-grained authorization
• Optional prompt and response security with Model Armor protection
• Centralized audit logging

For information about other MCP servers and information about security and governance controls available for Google Cloud MCP servers, see Google Cloud MCP servers overview.

Before you begin

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

1. Enable the BigQuery Migration Service API.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

   Enable the API

Required roles

To get the permissions that you need to enable the BigQuery Migration Service MCP server, ask your administrator to grant you the following IAM roles on the project where you want to enable the BigQuery Migration Service MCP server:

• Make MCP tool calls: MCP Tool User (roles/mcp.toolUser)
• Use the BigQuery Migration Service: Migration Workflow Editor (roles/bigquerymigration.editor)

For more information about granting roles, see Manage access to projects, folders, and organizations.

These predefined roles contain the permissions required to enable the BigQuery Migration Service MCP server. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to enable the BigQuery Migration Service MCP server:

• Make MCP tool calls: mcp.tools.call
• Use the BigQuery Migration Service:
  • bigquerymigration.workflows.create
  • bigquerymigration.workflows.get
  • bigquerymigration.workflows.list
  • bigquerymigration.workflows.delete
  • bigquerymigration.subtasks.get
  • bigquerymigration.subtasks.list

You might also be able to get these permissions with custom roles or other predefined roles.

Additional BigQuery Migration Service permissions might be required depending on the task. For information about BigQuery Migration Service roles and permissions, see BigQuery Migration Service roles and permissions.

Authentication and authorization

BigQuery Migration Service MCP servers use the OAuth 2.0 protocol with Identity and Access Management (IAM) for authentication and authorization. All Google Cloud identities are supported for authentication to MCP servers.

The BigQuery Migration Service MCP server doesn't accept API keys.

BigQuery Migration Service MCP OAuth scopes

OAuth 2.0 uses scopes and credentials to determine if an authenticated principal is authorized to take a specific action on a resource. For more information about OAuth 2.0 scopes at Google, see Using OAuth 2.0 to access Google APIs.

BigQuery Migration Service has the following MCP tool OAuth scopes:

Scope URI for gcloud CLI	Description
https://www.googleapis.com/auth/bigquerymigration	View and manage your workflows in BigQuery Migration Service and see the email address for your Google Account.
https://www.googleapis.com/auth/devstorage.read_only	This scope is required for query translations that read data from Cloud Storage.

Resources accessed during a tool call might require additional scopes.

Configure an MCP client to use the BigQuery Migration Service MCP server

Host programs, such as Claude or Gemini CLI, can instantiate MCP clients that connect to a single MCP server. A host program can have multiple clients that connect to different MCP servers. To connect to an MCP server, the MCP client must know at least the URL of the MCP server.

In your host, look for a way to connect to a MCP server. You're prompted to enter details about the server, such as its name and URL.

For the BigQuery Migration Service MCP server, enter the following as required:

• Server name: BigQuery Migration Service MCP server
• Server URL or Endpoint: bigquerymigration.googleapis.com/mcp
• Transport: HTTP

• Authentication details: your Google Cloud credentials, your OAuth Client ID, and secret, or an agent identity and credentials

  Which authentication details you choose depend on how you want to authenticate. For more information, see Authenticate to MCP servers.

For host-specific guidance, see the following:

• Gemini CLI MCP server setup
• Claude support: Getting started with custom connectors using remote MCP

For more general guidance, see Connect to remote MCP servers.

Available tools

To view details of available MCP tools and their descriptions for the BigQuery Migration Service MCP server, see the BigQuery Migration Service MCP reference.

List tools

Use the MCP inspector to list tools, or send a tools/list HTTP request directly to the BigQuery Migration Service MCP server. The tools/list method doesn't require authentication.

POST /mcp HTTP/1.1
Host: bigquerymigration.googleapis.com
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "tools/list",
}

Sample use cases

The following are sample use cases for the BigQuery Migration Service MCP server:

• Using an MCP client with an IDE, translate a query file into GoogleSQL syntax.
• Using an MCP client without an IDE, translate a specified query into GoogleSQL syntax.
• Assess translation quality.
• Get explanations of SQL translations.
• Generate a DDL statement for a specified query.

Sample prompts

You can use the following sample prompts to create and manage BigQuery Migration Service resources:

• Translate the DIALECT query in this FILENAME. Use PROJECT_ID and LOCATION. Persist the output and translation logs into separate directories.

  When you use this prompt, the MCP client calls the translate_query tool to translate the query in the specified file. The MCP client periodically calls the get_translation tool to get the results. After the translation completes, the client writes the output to the output directory and the logs to the logs directory.

• Translate this query from DIALECT: QUERY. Use PROJECT_ID and LOCATION.

  When you use this prompt, the MCP client calls the translate_query tool to translate the specified query and displays the translation results.

• Assess the translation quality.

  When you use this prompt, the MCP client reads and examines the translation logs and displays a summary of the translation issues with suggested next steps.

• Explain the translation.

  When you use this prompt, the MCP client calls the explain_translation tool to get an explanation of the translation. If the translation logs contain RelationNotFound or AttributeNotFound errors, the MCP client should suggest that you create a metadata package. If you can't generate the metadata, you can send a prompt that requests the DDL statement.

  A sample response looks like the following:

  The translated code converts Teradata-specific features into their
  BigQuery equivalents. Here's a breakdown of the key changes:
  * `MACRO` to `PROCEDURE`: The `YourMacroName` macro was converted
  into a BigQuery stored procedure because
  BigQuery doesn't support macros.
  * `SELECT INTO` to `SET`:
    * For setting multiple `OUT` parameters in `YourStoredProcedureName`, the
      `SELECT ... INTO` is changed to `SET (...) = (SELECT STRUCT(...))`.
    * For single variable assignment in `YourOtherProcedureName`,
      `SELECT ... INTO` is replaced by `SET variable = (SELECT ...)` which is
      the standard in BigQuery.
  * Atomic Operations to `MERGE: The BEGIN REQUEST ... END REQUEST` blocks in
    the `ProcedureA`, `ProcedureB`, and `ProcedureC` procedures,
    which perform atomic "update or insert" operations, are translated into
    standard SQL `MERGE` statements. This is the correct and modern way to
    handle this logic in BigQuery.
  

• Generate DDL for this input query.

  The MCP client calls the generate_ddl_suggestion tool to start a suggestion job. The client gets the suggestion results by calling the fetch_ddl_suggestion tool. When the suggestion is available, the MCP client displays it.

  If the DDL statements are correct, you can send a prompt to prepend the generated DDL statements to the query to improve the translation quality.

• Prepend the generated DDL statements to the input query and retranslate.

  When you use this prompt, the MCP client prepends the DDL statements to the original input query and calls the translate_query tool. The client calls the get_translation tool to get the translation. The new query translation and the logs persist when they're available.

  If the generated DDL statements are correct, any RelationNotFound or AttributeNotFound errors should be resolved which results in improved translation quality.

In the prompts, replace the following:

• DIALECT: The dialect of the SQL query you're translating.
• QUERY: The query you're translating.
• FILENAME: The file that contains the query you're translating.
• PROJECT_NUMBER: Your Google Cloud project number.
• LOCATION: The location of the SQL translator.

Optional security and safety configurations

MCP introduces new security risks and considerations due to the wide variety of actions that you can take with MCP tools. To minimize and manage these risks, Google Cloud offers defaults and customizable policies to control the use of MCP tools in your Google Cloud organization or project.

For more information about MCP security and governance, see AI security and safety.

Use Model Armor

Model Armor is a Google Cloud service designed to enhance the security and safety of your AI applications. It works by proactively screening LLM prompts and responses, protecting against various risks and supporting responsible AI practices. Whether you are deploying AI in your cloud environment, or on external cloud providers, Model Armor can help you prevent malicious input, verify content safety, protect sensitive data, maintain compliance, and enforce your AI safety and security policies consistently across your diverse AI landscape.

Model Armor is only available in specific regional locations. If Model Armor is enabled for a project, and a call to that project comes from an unsupported region, then Model Armor isn't called and the content is not scanned by Model Armor. For more information, see Model Armor locations.

Caution: If a request fails, Model Armor logs the entire payload. This might expose sensitive information in the logs.

Enable Model Armor

You must enable Model Armor APIs before you can use Model Armor.

Console

1. Enable the Model Armor API.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

   Enable the API

2. Select the project where you want to activate Model Armor.

gcloud

Before you begin, follow these steps using the Google Cloud CLI with the Model Armor API:

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Run the following command to set the API endpoint for the Model Armor service.

   gcloud config set api_endpoint_overrides/modelarmor "https://modelarmor.LOCATION.rep.googleapis.com/"

   Replace LOCATION with the region where you want to use Model Armor.

Configure protection for Google and Google Cloud remote MCP servers

To help protect your MCP tool calls and responses you can use Model Armor floor settings. A floor setting defines the minimum security filters that apply across the project. This configuration applies a consistent set of filters to all MCP tool calls and responses within the project.

Tip: Don't enable the prompt injection and jailbreak filter unless your MCP traffic carries natural language data.

Set up a Model Armor floor setting with MCP sanitization enabled. For more information, see Configure Model Armor floor settings.

Note: If the agent and the MCP server are in different projects, you can create floor settings in both projects (the client project and the resource project). In this case, Model Armor is invoked twice, once for each project.

See the following example command:

gcloud model-armor floorsettings update \
--full-uri='projects/PROJECT_ID/locations/global/floorSetting' \
--enable-floor-setting-enforcement=TRUE \
--add-integrated-services=GOOGLE_MCP_SERVER \
--google-mcp-server-enforcement-type=INSPECT_AND_BLOCK \
--enable-google-mcp-server-cloud-logging \
--malicious-uri-filter-settings-enforcement=ENABLED \
--add-rai-settings-filters='[{"confidenceLevel": "MEDIUM_AND_ABOVE", "filterType": "DANGEROUS"}]'

Replace PROJECT_ID with your Google Cloud project ID.

Note the following settings:

• INSPECT_AND_BLOCK: The enforcement type that inspects content for the Google MCP server and blocks prompts and responses that match the filters.
• ENABLED: The setting that enables a filter or enforcement.
• MEDIUM_AND_ABOVE: The confidence level for the Responsible AI - Dangerous filter settings. You can modify this setting, though lower values might result in more false positives. For more information, see Model Armor confidence levels.

Disable scanning MCP traffic with Model Armor

If you want to stop scanning Google MCP traffic with Model Armor, run the following command:

gcloud model-armor floorsettings update \
  --full-uri='projects/PROJECT_ID/locations/global/floorSetting' \
  --remove-integrated-services=GOOGLE_MCP_SERVER

Replace PROJECT_ID with the Google Cloud project ID.

Model Armor won't scan MCP traffic in the project.

Control MCP use with IAM deny policies

Identity and Access Management (IAM) deny policies help you secure Google Cloud remote MCP servers. Configure these policies to block unwanted MCP tool access.

For example, you can deny or allow access based on:

• The principal
• Tool properties like read-only
• The application's OAuth client ID

For more information, see Control MCP use with Identity and Access Management.

Quotas and limits

The BigQuery Migration Service MCP server doesn't have its own quotas. There is no limit on the number of calls you can make to the MCP server.

You are still subject to the quotas that the APIs called by the MCP server tools enforce. For more information, see BigQuery Migration Service API on the Quotas and limits page.

What's next

• Read the BigQuery Migration Service MCP reference documentation.
• Learn more about Google Cloud MCP servers.
• See the MCP supported products.