MCP Tools Reference: dataform.googleapis.com

Tool: 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.

The following code sample shows how to use curl to call the create_workspace MCP tool.

Curl Request 
curl --location 'https://dataform.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "create_workspace",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Input Schema

CreateWorkspace request message.

CreateWorkspaceRequest

JSON representation 
{
  "parent": string,
  "workspace": {
    object (Workspace)
  },
  "workspaceId": string
}
Fields
parent

string

Required. The repository in which to create the workspace. Must be in the format projects/*/locations/*/repositories/*.
workspace

object (Workspace)

Required. The workspace to create.
workspaceId

string

Required. The ID to use for the workspace, which will become the final component of the workspace's resource name.

Workspace

JSON representation 
{
  "name": string,
  "createTime": string,
  "dataEncryptionState": {
    object (DataEncryptionState)
  },
  "privateResourceMetadata": {
    object (PrivateResourceMetadata)
  },
  "depth": integer,

  // Union field _internal_metadata can be only one of the following:
  "internalMetadata": string
  // End of list of possible types for union field _internal_metadata.

  // Union field _disable_moves can be only one of the following:
  "disableMoves": boolean
  // End of list of possible types for union field _disable_moves.

  // Union field _original_branch can be only one of the following:
  "originalBranch": string
  // End of list of possible types for union field _original_branch.

  // Union field _enable_branch_management can be only one of the following:
  "enableBranchManagement": boolean
  // End of list of possible types for union field _enable_branch_management.

  // Union field _shallow can be only one of the following:
  "shallow": boolean
  // End of list of possible types for union field _shallow.
}
Fields
name

string

Identifier. The workspace's name.
createTime

string (Timestamp format)

Output only. The timestamp of when the workspace was created.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
dataEncryptionState

object (DataEncryptionState)

Output only. A data encryption state of a Git repository if this Workspace is protected by a KMS key.
privateResourceMetadata

object (PrivateResourceMetadata)

Output only. Metadata indicating whether this resource is user-scoped. For Workspace resources, the user_scoped field is always true.
depth

integer

Optional. Input only. Immutable. The maximum depth of the Git repository to checkout for this workspace. If defined and greater than 0, the Git repository will be created as a shallow clone with the given depth, otherwise a full clone will be performed. This field is available only for GitHub, GitLab and 1p repositories with enabled branch management.

Union field _internal_metadata.

_internal_metadata can be only one of the following:
internalMetadata

string

Output only. All the metadata information that is used internally to serve the resource. For example: timestamps, flags, status fields, etc. The format of this field is a JSON string.

Union field _disable_moves.

_disable_moves can be only one of the following:
disableMoves

boolean

Optional. If set to true, workspaces will not be moved if its linked Repository is moved. Instead, it will be deleted.

Union field _original_branch.

_original_branch can be only one of the following:
originalBranch

string

Optional. Input only. Immutable. The name of the default upstream branch for all pull/push operations in the remote repository for this workspace. If empty, the HEAD branch from repository will be used.

Union field _enable_branch_management.

_enable_branch_management can be only one of the following:
enableBranchManagement

boolean

Immutable. Controls the enablement of branch checkout for the workspace.

When set to True, the workspace will be allowed to checkout branches.

Union field _shallow.

_shallow can be only one of the following:
shallow

boolean

Output only. If set to true, the workspace was created as a shallow clone. Will be set to true if the depth field is set to a value greater than 0, otherwise it will be set to false.

Timestamp

JSON representation 
{
  "seconds": string,
  "nanos": integer
}
Fields
seconds

string (int64 format)

Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be between -62135596800 and 253402300799 inclusive (which corresponds to 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z).
nanos

integer

Non-negative fractions of a second at nanosecond resolution. This field is the nanosecond portion of the duration, not an alternative to seconds. Negative second values with fractions must still have non-negative nanos values that count forward in time. Must be between 0 and 999,999,999 inclusive.

DataEncryptionState

JSON representation 
{
  "kmsKeyVersionName": string
}
Fields
kmsKeyVersionName

string

Required. The KMS key version name with which data of a resource is encrypted.

PrivateResourceMetadata

JSON representation 
{
  "userScoped": boolean
}
Fields
userScoped

boolean

Output only. If true, this resource is user-scoped, meaning it is either a workspace or sourced from a workspace.

Output Schema

Represents a Dataform Git workspace.

Workspace

JSON representation 
{
  "name": string,
  "createTime": string,
  "dataEncryptionState": {
    object (DataEncryptionState)
  },
  "privateResourceMetadata": {
    object (PrivateResourceMetadata)
  },
  "depth": integer,

  // Union field _internal_metadata can be only one of the following:
  "internalMetadata": string
  // End of list of possible types for union field _internal_metadata.

  // Union field _disable_moves can be only one of the following:
  "disableMoves": boolean
  // End of list of possible types for union field _disable_moves.

  // Union field _original_branch can be only one of the following:
  "originalBranch": string
  // End of list of possible types for union field _original_branch.

  // Union field _enable_branch_management can be only one of the following:
  "enableBranchManagement": boolean
  // End of list of possible types for union field _enable_branch_management.

  // Union field _shallow can be only one of the following:
  "shallow": boolean
  // End of list of possible types for union field _shallow.
}
Fields
name

string

Identifier. The workspace's name.
createTime

string (Timestamp format)

Output only. The timestamp of when the workspace was created.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
dataEncryptionState

object (DataEncryptionState)

Output only. A data encryption state of a Git repository if this Workspace is protected by a KMS key.
privateResourceMetadata

object (PrivateResourceMetadata)

Output only. Metadata indicating whether this resource is user-scoped. For Workspace resources, the user_scoped field is always true.
depth

integer

Optional. Input only. Immutable. The maximum depth of the Git repository to checkout for this workspace. If defined and greater than 0, the Git repository will be created as a shallow clone with the given depth, otherwise a full clone will be performed. This field is available only for GitHub, GitLab and 1p repositories with enabled branch management.

Union field _internal_metadata.

_internal_metadata can be only one of the following:
internalMetadata

string

Output only. All the metadata information that is used internally to serve the resource. For example: timestamps, flags, status fields, etc. The format of this field is a JSON string.

Union field _disable_moves.

_disable_moves can be only one of the following:
disableMoves

boolean

Optional. If set to true, workspaces will not be moved if its linked Repository is moved. Instead, it will be deleted.

Union field _original_branch.

_original_branch can be only one of the following:
originalBranch

string

Optional. Input only. Immutable. The name of the default upstream branch for all pull/push operations in the remote repository for this workspace. If empty, the HEAD branch from repository will be used.

Union field _enable_branch_management.

_enable_branch_management can be only one of the following:
enableBranchManagement

boolean

Immutable. Controls the enablement of branch checkout for the workspace.

When set to True, the workspace will be allowed to checkout branches.

Union field _shallow.

_shallow can be only one of the following:
shallow

boolean

Output only. If set to true, the workspace was created as a shallow clone. Will be set to true if the depth field is set to a value greater than 0, otherwise it will be set to false.

Timestamp

JSON representation 
{
  "seconds": string,
  "nanos": integer
}
Fields
seconds

string (int64 format)

Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be between -62135596800 and 253402300799 inclusive (which corresponds to 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z).
nanos

integer

Non-negative fractions of a second at nanosecond resolution. This field is the nanosecond portion of the duration, not an alternative to seconds. Negative second values with fractions must still have non-negative nanos values that count forward in time. Must be between 0 and 999,999,999 inclusive.

DataEncryptionState

JSON representation 
{
  "kmsKeyVersionName": string
}
Fields
kmsKeyVersionName

string

Required. The KMS key version name with which data of a resource is encrypted.

PrivateResourceMetadata

JSON representation 
{
  "userScoped": boolean
}
Fields
userScoped

boolean

Output only. If true, this resource is user-scoped, meaning it is either a workspace or sourced from a workspace.

Tool Annotations

Tool annotations are sent to MCP clients to describe the basic risk of a given tool. Most clients treat these hints as untrusted, but they can be used to decide when a confirmation prompt might be sent to a user.

Along with the title string, the following boolean hints are defined as follows:

  • readOnlyHint: If true, the tool doesn't modify its environment. Default: false.
  • destructiveHint: If true, then the tool can perform destructive actions. If false, then the tool can only perform additive actions. Default: true.
  • idempotentHint: If true, then calling the tool repeatedly with the same arguments will have no additional effect on its environment. Default: false.
  • openWorldHint: If true, then the tool can interact with an 'open world' of external entities. If false, then the tool can only interact with internal entities. For example, a web search tool would be open world, while a memory tool would not be open world.

Destructive Hint: ❌ | Idempotent Hint: ❌ | Read Only Hint: ❌ | Open World Hint: ❌