MCP Reference: dataform.googleapis.com

Dataform MCP server provides tools to interact with Dataform.

A Model Context Protocol (MCP) server acts as a proxy between an external service that provides context, data, or capabilities to a Large Language Model (LLM) or AI application. MCP servers connect AI applications to external systems such as databases and web services, translating their responses into a format that the AI application can understand.

Server Setup

You must enable MCP servers and set up authentication before use. For more information about using Google and Google Cloud remote MCP servers, see Google Cloud MCP servers overview.

Server Endpoints

An MCP service endpoint is the network address and communication interface (usually a URL) of the MCP server that an AI application (the Host for the MCP client) uses to establish a secure, standardized connection. It is the point of contact for the LLM to request context, call a tool, or access a resource. Google MCP endpoints can be global or regional.

The Dataform API MCP server has the following global MCP endpoint:

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

MCP Tools

An MCP tool is a function or executable capability that an MCP server exposes to a LLM or AI application to perform an action in the real world.

Tools

The dataform.googleapis.com MCP server has the following tools:

MCP Tools
list_repositories

List the Dataform repositories in a given Google Cloud project and location.

The parent parameter value must be in the format projects/{project_id}/locations/{location}.
create_repository

Create a new Dataform repository in a given Google Cloud project and location.

This tool establishes the root resource required for all other transformation assets, such as compilation results and workflow configurations. A repository must be created before any other Dataform MCP tool can be used. Enabling this tool is the first step in setting up a Dataform project.

The parent parameter value must be in the format projects/{project_id}/locations/{location}.

The repository_id parameter value is the ID to use for the repository.

Omit the strictActAsChecks parameter to leave it unset on a new repository. Note that strict act-as checks are enforced for new projects by default, so executing a workflow in this repository requires a custom service account.
commit_repository_changes

Apply a Git commit to record the state of files within a Dataform repository.

This tool is primarily intended for managing single-file assets—such as notebooks or saved queries—that reside directly in the repository. This tool isn't used in typical pipeline workflows that require workspaces.

Don't use this tool on repositories connected to a remote Git host. To verify, use the get_repository tool. If the git_remote_settings field is present, the repository is connected to a remote host and you must use workspace-based tools such as commit_workspace_changes instead.

This commit action creates a permanent entry in the repository's internal Git history.

The name parameter value must be in the format projects/{project_id}/locations/{location}/repositories/{repository}.
read_repository_file

Return the contents of a file that's inside a Dataform repository.

This tool isn't for standard pipeline development. It's intended for direct repository interaction, typically for managing single-file assets such as notebooks or saved queries.

Don't use this tool on repositories connected to a remote Git host. To verify, use the get_repository tool. If the git_remote_settings field is present, the repository is connected to a remote host and you must use the read_file tool to read the file from a workspace instead.

The name parameter value refers to the repository and must be in the format projects/{project_id}/locations/{location}/repositories/{repository}.

The path parameter value must be relative to the repository root. Don't use directory traversal, such as ... Use the query_repository_directory_contents tool to obtain valid file paths.
query_repository_directory_contents

Return the contents of a given Dataform repository directory.

This tool is primarily used to list and manage single-file assets directly in the repository.

Don't use this tool on repositories connected to a remote Git host. To verify, use the get_repository tool. If the git_remote_settings field is present, the repository is connected to a remote host and you must use the query_directory_contents tool to list a workspace directory instead.

The name parameter value refers to the repository in the format projects/{project_id}/locations/{location}/repositories/{repository}.

The path parameter value must be relative to the repository root. Don't use directory traversal, such as ... If left empty, the repository root is used.
list_workflow_configs

List the workflow configurations in a given Dataform repository.

The parent parameter value must be in the format projects/{project_id}/locations/{location}/repositories/{repository}.
get_workflow_config

Fetch a single Dataform workflow configuration.

The name parameter value must be in the format projects/{project_id}/locations/{location}/repositories/{repository}/workflowConfigs/{workflow_config}.
create_workflow_config

Create a new workflow configuration in a given Dataform repository.

The parent parameter value must be in the format projects/{project_id}/locations/{location}/repositories/{repository}.

The workflow_config_id is the ID for the workflow configuration.

A workflow configuration pairs a ReleaseConfig with a schedule and an identity. The ReleaseConfig determines which code is compiled, while this tool determines when that code runs and which service account runs it.

Prerequisite: You must first create a ReleaseConfig using the create_release_config tool. The workflow_config.release_config parameter value is required, and the request fails without it.

Workflow invocations created from this workflow configuration run under a custom service account. To specify this service account, set the invocationConfig.serviceAccount parameter value. If omitted, invocations fall back to using the repository's service_account. The service account can't be the default Dataform service agent. The service account must have the necessary permissions to execute the workflow, and the user must be authorized to act as the selected account. This authorization is typically granted through the Service Account User (roles/iam.serviceAccountUser) IAM role, which can be granted on the service account itself or on the project that contains it.
update_workflow_config

Update the properties of an existing Dataform workflow configuration, such as its execution schedule (cron), associated release configuration, or invocation overrides.

Modifications to the cron_schedule take effect immediately for all future scheduled executions.

The name parameter value must be in the format projects/{project_id}/locations/{location}/repositories/{repository}/workflowConfigs/{workflow_config}.

The workflow_config.release_config parameter value is strictly required for every update. Use the get_workflow_config tool to read the current workflow configuration, and include its release_config value in your update request.

Workflow invocations created from this workflow configuration run under a custom service account. To specify this service account, set the invocationConfig.serviceAccount parameter value. If omitted, invocations fall back to using the repository's service_account. The service account can't be the default Dataform service agent. The service account must have the necessary permissions to execute the workflow, and the user must be authorized to act as the selected service account. This authorization is typically granted through the Service Account User (roles/iam.serviceAccountUser) IAM role, which can be granted on the service account itself or on the project that contains it.
list_release_configs

List the release configurations in a given Dataform repository.

The parent parameter value must be in the format projects/{project_id}/locations/{location}/repositories/{repository}.
get_release_config

Fetch a single Dataform release configuration.

The name parameter value must be in the format projects/{project_id}/locations/{location}/repositories/{repository}/releaseConfigs/{release_config}.
create_release_config

Create a new release configuration in a given Dataform repository.

The parent parameter value must be in the format projects/{project_id}/locations/{location}/repositories/{repository}.

The release_config_id is the user-defined ID for the release configuration. If the user doesn't specify an ID, generate a short, descriptive ID using lowercase letters, numbers, and hyphens based on their request.

Omit the release_config.cron_schedule parameter value for Google-hosted repositories. To verify, use the get_repository tool. If the git_remote_settings field is missing, the repository is Google-hosted. To schedule the pipeline, set the schedule using the create_workflow_config tool.
update_release_config

Update an existing Dataform release configuration, which serves as a template for automatic code compilation.

Updates to fields like git_commitish change how future compilation results are generated, but such updates don't retroactively alter existing CompilationResult assets.

Omit the release_config.cron_schedule parameter value when updating Google-hosted repositories. To verify, use the get_repository tool. If the git_remote_settings field is missing, the repository is Google-hosted. To schedule the pipeline, set or update the schedule using the create_workflow_config or update_workflow_config tools.

The name parameter value must be in the format projects/{project_id}/locations/{location}/repositories/{repository}/releaseConfigs/{release_config}.
create_compilation_result

Create a new Dataform compilation result in a given Google Cloud project and location.

This tool compiles .sqlx files into executable SQL. Agents need to know that subsequent code changes aren't reflected in this result unless a new compilation is triggered.

The parent parameter value must be in the format projects/{project_id}/locations/{location}/repositories/{repository}.

Agents can validate the compiled SQL by inspecting CompilationResultAction resources and potentially using a BigQuery tool for a dry run.

A valid compilation result is required before triggering a manual workflow invocation using the create_workflow_invocation tool.

Prerequisite: Create a repository using the create_repository tool before calling the create_compilation_result tool.
list_workflow_invocations

List the workflow invocations in a given Dataform repository.

The parent parameter value must be in the format projects/{project_id}/locations/{location}/repositories/{repository}.
create_workflow_invocation

Create a new workflow invocation in a given Dataform repository.

The parent parameter value must be in the format projects/{project_id}/locations/{location}/repositories/{repository}.

Either the compilation_result or the workflow_config parameter value is required.

  • If using compilation_result, the parameter value must be in the format projects/{project_id}/locations/{location}/repositories/{repository}/compilationResults/{compilation_result}.
  • If using workflow_config, the parameter value must be in the format projects/{project_id}/locations/{location}/repositories/{repository}/workflowConfigs/{workflow_config}.

Prerequisite: To trigger an invocation, you must first create either a compilation_result using the create_compilation_result tool or a workflow_config using the create_workflow_config tool. You can't trigger an invocation directly from raw repository code.

The workflow invocation runs under a service account determined by the compilation source:

  • If using compilation_result, set the invocationConfig.serviceAccount parameter value. If omitted, the repository's default service_account is used.
  • If using workflow_config, don't set the invocationConfig parameter. The invocation automatically runs under the service account configured on that workflow configuration.

The service account can't be the default Dataform service agent. The service account must have the necessary permissions to execute the workflow, and the user must be authorized to act as the selected service account. This authorization is typically granted through the Service Account User role (roles/iam.serviceAccountUser), which can be granted on the service account itself or on the project that contains it.
cancel_workflow_invocation

Request the graceful termination of a running Dataform workflow invocation.

This tool sends a cancellation signal to the running workflow. However, any individual BigQuery jobs, table creations, or assertions that have already completed as part of this workflow will not be rolled back.

The name parameter value must be in the format projects/{project_id}/locations/{location}/repositories/{repository}/workflowInvocations/{workflow_invocation}.
get_compilation_result

Fetch a single Dataform compilation result.

The name parameter value must be in the format projects/{project_id}/locations/{location}/repositories/{repository}/compilationResults/{compilation_result}.
query_compilation_actions

Return the compilation result actions for a given Dataform compilation result.

The name parameter value must be in the format projects/{project_id}/locations/{location}/repositories/{repository}/compilationResults/{compilation_result}.
query_workflow_invocation_actions

Return the workflow invocation actions for a given Dataform workflow invocation.

These actions represent the individual BigQuery jobs, table creations, or assertions that make up the workflow.

The name parameter value must be in the format projects/{project_id}/locations/{location}/repositories/{repository}/workflowInvocations/{workflow_invocation}.
get_workflow_invocation

Fetch a single Dataform workflow invocation.

The name parameter value must be in the format projects/{project_id}/locations/{location}/repositories/{repository}/workflowInvocations/{workflow_invocation}.
list_workspaces

List the development workspaces in a given Dataform repository.

Use this tool to discover existing workspaces before performing file operations (using tools such as read_file or write_file) or committing code (using a tool such as commit_workspace_changes).

The parent parameter value must be in the format projects/{project_id}/locations/{location}/repositories/{repository}.
get_workspace

Fetch a single Dataform development workspace.

The name parameter value must be in the format projects/{project_id}/locations/{location}/repositories/{repository}/workspaces/{workspace}.

If you don't know the exact workspace name, use the list_workspaces tool to find it.
create_workspace

Create a new development workspace in a given Dataform repository.

A workspace is an isolated, editable checkout of the repository. Use a workspace when you need to author or revise pipeline code across several files and validate it before committing. Edit files in the workspace with the write_file and remove_file tools, record the result with the commit_workspace_changes tool, and publish the committed changes to the repository with the push_git_commits tool.

Don't use the commit_repository_changes tool for standard pipeline development. That tool writes directly to the repository, is intended only for single-file assets such as notebooks or saved queries, and fails on repositories connected to a remote Git host.

Prerequisite: The parent repository must exist.

The parent parameter value must be in the format projects/{project_id}/locations/{location}/repositories/{repository}.

The workspace_id parameter value is the ID to use for the workspace.

The workspace parameter value holds the workspace to create.
query_directory_contents

Return the contents of a given directory inside a Dataform workspace.

Use this tool to discover valid file paths before calling the read_file or write_file tools.

The workspace parameter value must be in the format projects/{project_id}/locations/{location}/repositories/{repository}/workspaces/{workspace}.

The path parameter value is the relative path to the directory from the workspace root. Don't use directory traversal, such as ... If omitted, the workspace root is used.
search_files

Find files and directories in a Dataform workspace that match a search filter.

Use this tool instead of recursively listing directories with the query_directory_contents tool when locating a file by name or extension across a large repository.

The workspace parameter value must be in the format projects/{project_id}/locations/{location}/repositories/{repository}/workspaces/{workspace}.

The filter parameter value restricts the results. Filtering is only supported on the path field (for example, path="*.sqlx" or path="definitions/model.sqlx").
read_file

Return the contents of a file inside a Dataform workspace, including uncommitted changes.

Use this tool to read the workspace's workflow_settings.yaml file, which holds the pipeline's compilation settings such as the default BigQuery dataset, default location, and Dataform core version. This file sits at the root of the pipeline's directory, which is not necessarily the workspace root, as a repository can hold several pipelines in subdirectories. Locate the file with the search_files tool.

To read a committed file directly from the repository without a workspace, use the read_repository_file tool instead. Note that read_repository_file only works on repositories that are not connected to a remote Git host.

The workspace parameter value must be in the format projects/{project_id}/locations/{location}/repositories/{repository}/workspaces/{workspace}.

The path parameter value is the relative path to the file from the workspace root. Do not use directory traversal, such as ... Valid paths can be obtained using the query_directory_contents or search_files tools.

The revision parameter value optionally selects a specific Git revision of the file. If omitted, the current uncommitted state of the file is returned.
write_file

Write the contents of a file inside a Dataform workspace, creating the file if it does not exist.

The supplied contents parameter value replaces the whole file, so read current contents with the read_file tool before making a partial edit. Changes stay uncommitted until the commit_workspace_changes tool is called.

The workspace parameter value must be in the format projects/{project_id}/locations/{location}/repositories/{repository}/workspaces/{workspace}.

The path parameter value is the relative path to the file from the workspace root. Don't use directory traversal, such as ...

The contents parameter value must be a base64-encoded string containing the file content.
remove_file

Delete a file inside a Dataform workspace.

The deletion stays uncommitted until the commit_workspace_changes tool is called.

The workspace parameter value must be in the format projects/{project_id}/locations/{location}/repositories/{repository}/workspaces/{workspace}.

The path parameter value is the relative path to the file from the workspace root. Don't use directory traversal, such as ... Valid file paths can be obtained using the query_directory_contents or search_files tools.
make_directory

Create a directory inside a Dataform workspace, including any missing parent directories.

The workspace parameter value must be in the format projects/{project_id}/locations/{location}/repositories/{repository}/workspaces/{workspace}.

The path parameter value is the relative path to the directory from the workspace root. Don't use directory traversal, such as ...
commit_workspace_changes

Record a Git commit for the uncommitted changes in a Dataform workspace.

The commit stays local to the workspace until it's published with the push_git_commits tool.

By default, all uncommitted changes are committed. To commit only a subset of files, supply the paths parameter value.

The name parameter value must be in the format projects/{project_id}/locations/{location}/repositories/{repository}/workspaces/{workspace}.

The author parameter value identifies the Git author recorded for the commit. Both author.name and author.email_address are required. Supply the values that identify the user on whose behalf the commit is made. Don't use placeholders, because they're written into the Git history.

The commit_message parameter value is the commit's message.
push_git_commits

Push a Dataform workspace's committed changes to the repository's Git remote.

Prerequisite: You must commit workspace edits using the commit_workspace_changes tool before pushing. Uncommitted edits stay local and aren't pushed.

If you plan to use the create_release_config tool, you must push your commits first. A release configuration resolves its git_commitish against the Git remote, so a branch or commit that exists only in the local workspace is invisible to it.

The name parameter value must be in the format projects/{project_id}/locations/{location}/repositories/{repository}/workspaces/{workspace}.

The remote_branch parameter value is the remote branch to push to. If omitted, a workspace with branch management enabled pushes to its currently checked-out branch, and any other workspace pushes to the repository's configured default branch.
get_repository

Fetch a single Dataform repository, including its Git remote settings, workspace compilation overrides, and default service account.

Use this tool to check the git_remote_settings field to determine how to interact with the repository. If the git_remote_settings field is present, the repository is connected to a remote Git host, which means you must use workspace-based tools for pipeline development, such as create_workspace or commit_workspace_changes. If the field is missing, the repository is Google-hosted. You can still use workspaces in this case for pipeline development. Direct repository tools like commit_repository_changes are not recommended unless you are managing single-file assets.

The name parameter value must be in the format projects/{project_id}/locations/{location}/repositories/{repository}.

If you don't know the exact repository name, use the list_repositories tool to find it.
update_repository

Update the properties of an existing Dataform repository, such as its Git remote settings, workspace compilation overrides, or the default service account.

Prerequisite: Use the get_repository tool to read the current repository state before updating.

If the update_mask parameter value is omitted, all mutable fields are overwritten with the values supplied in the repository parameter value. To modify only specific fields without clearing the others, list those fields in update_mask.

The repository.name parameter value must be in the format projects/{project_id}/locations/{location}/repositories/{repository}.
create_folder

Create a new Dataform folder in a given Google Cloud project and location.

Folders organize Dataform repositories into a hierarchy. Creating a folder doesn't move any repositories into it. To place a repository inside a folder, set the containing_folder parameter value when using the create_repository tool.

Don't attempt to move an existing repository into a folder using the update_repository tool. Once a repository is created, its containing_folder field can't be modified using MCP tools.

The parent parameter value must be in the format projects/{project_id}/locations/{location}.

The folder.display_name parameter value is required and specifies the folder's user-friendly name.

Get MCP tool specifications

To get the MCP tool specifications for all tools in an MCP server, use the tools/list method. The following example demonstrates how to use curl to list all tools and their specifications currently available within the MCP server.

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