create_workspace
Create a new Terraform Cloud workspace to manage infrastructure configurations in an isolated environment. Define variables, execution mode, VCS repo settings, and automate workflows for efficient infrastructure management.
Instructions
Create a new workspace in an organization.
Copy
Creates a new Terraform Cloud workspace which serves as an isolated environment
for managing infrastructure. Workspaces contain variables, state files, and run
histories for a specific infrastructure configuration.
API endpoint: POST /organizations/{organization}/workspaces
Args:
organization: The name of the organization
name: The name to give the workspace
params: Additional workspace parameters (optional):
- description: Human-readable description of the workspace
- execution_mode: How Terraform runs are executed (remote, local, agent)
- terraform_version: Version of Terraform to use (default: latest)
- working_directory: Subdirectory to use when running Terraform
- vcs_repo: Version control repository configuration
- auto_apply: Whether to automatically apply successful plans
- file_triggers_enabled: Whether file changes trigger runs
- trigger_prefixes: Directories that trigger runs when changed
- trigger_patterns: Glob patterns that trigger runs when files match
- allow_destroy_plan: Whether to allow destruction plans
- auto_apply_run_trigger: Whether to auto-apply changes from run triggers
Returns:
The created workspace data including configuration, settings and metadata
See:
docs/tools/workspace_tools.md for usage examples
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| organization | Yes | ||
| params | No |
Input Schema (JSON Schema)
{
"$defs": {
"ExecutionMode": {
"description": "Execution mode options for workspaces and organizations.\n\nDefines how Terraform operations are executed:\n- REMOTE: Terraform runs on Terraform Cloud's infrastructure\n- LOCAL: Terraform runs on your local machine\n- AGENT: Terraform runs on your own infrastructure using an agent\n\nReference: https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings#execution-mode\n\nSee:\n docs/models/workspace_examples.md for usage examples",
"enum": [
"remote",
"local",
"agent"
],
"title": "ExecutionMode",
"type": "string"
},
"VcsRepoConfig": {
"description": "VCS repository configuration for a workspace.\n\nDefines version control system repository configuration for a workspace,\nincluding branch, repository identifier, OAuth token, and other settings.\n\nReference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/workspaces\n\nSee:\n docs/models/workspace_examples.md for usage examples",
"properties": {
"branch": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The repository branch that Terraform executes from",
"title": "Branch"
},
"github-app-installation-id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The VCS Connection GitHub App Installation to use",
"title": "Github-App-Installation-Id"
},
"identifier": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "A reference to your VCS repository in the format :org/:repo",
"title": "Identifier"
},
"ingress-submodules": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether submodules should be fetched when cloning the VCS repository",
"title": "Ingress-Submodules"
},
"oauth-token-id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Specifies the VCS OAuth connection and token",
"title": "Oauth-Token-Id"
},
"tags-regex": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "A regular expression used to match Git tags",
"title": "Tags-Regex"
}
},
"title": "VcsRepoConfig",
"type": "object"
},
"WorkspaceParams": {
"description": "Parameters for workspace operations without routing fields.\n\nThis model provides all optional parameters for creating or updating workspaces,\nreusing field definitions from BaseWorkspaceRequest. It separates configuration\nparameters from routing information like organization and workspace name.\n\nReference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/workspaces\n\nNote:\n When updating a workspace, use this model to specify only the attributes\n you want to change. Unspecified attributes retain their current values.\n All fields are inherited from BaseWorkspaceRequest.\n\nSee:\n docs/models/workspace_examples.md for usage examples",
"properties": {
"agent-pool-id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The ID of the agent pool",
"title": "Agent-Pool-Id"
},
"allow-destroy-plan": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": true,
"description": "Whether to allow destruction plans",
"title": "Allow-Destroy-Plan"
},
"assessments-enabled": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": false,
"description": "Whether to perform health assessments",
"title": "Assessments-Enabled"
},
"auto-apply": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": false,
"description": "Whether to automatically apply changes in runs triggered by VCS, UI, or CLI",
"title": "Auto-Apply"
},
"auto-apply-run-trigger": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": false,
"description": "Whether to automatically apply changes initiated by run triggers",
"title": "Auto-Apply-Run-Trigger"
},
"auto-destroy-activity-duration": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Value and units for automatically scheduled destroy runs based on workspace activity",
"title": "Auto-Destroy-Activity-Duration"
},
"auto-destroy-at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Timestamp when the next scheduled destroy run will occur",
"title": "Auto-Destroy-At"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Description of the workspace",
"title": "Description"
},
"execution-mode": {
"anyOf": [
{
"type": "string"
},
{
"$ref": "#/$defs/ExecutionMode"
},
{
"type": "null"
}
],
"default": "remote",
"description": "How operations are executed",
"title": "Execution-Mode"
},
"file-triggers-enabled": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": true,
"description": "Whether to filter runs based on file paths",
"title": "File-Triggers-Enabled"
},
"global-remote-state": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": false,
"description": "Whether to allow all workspaces to access this workspace's state",
"title": "Global-Remote-State"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Name of the workspace",
"title": "Name"
},
"queue-all-runs": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": false,
"description": "Whether runs should be queued immediately",
"title": "Queue-All-Runs"
},
"setting-overwrites": {
"anyOf": [
{
"additionalProperties": {
"type": "boolean"
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Specifies attributes that have organization-level defaults",
"title": "Setting-Overwrites"
},
"source-name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Indicates where the workspace settings originated",
"title": "Source-Name"
},
"source-url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "URL to origin source",
"title": "Source-Url"
},
"speculative-enabled": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": true,
"description": "Whether this workspace allows speculative plans",
"title": "Speculative-Enabled"
},
"terraform-version": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": "latest",
"description": "Specifies the version of Terraform to use for this workspace",
"title": "Terraform-Version"
},
"trigger-patterns": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "List of glob patterns that trigger runs",
"title": "Trigger-Patterns"
},
"trigger-prefixes": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "List of paths that trigger runs",
"title": "Trigger-Prefixes"
},
"vcs-repo": {
"anyOf": [
{
"$ref": "#/$defs/VcsRepoConfig"
},
{
"type": "null"
}
],
"default": null,
"description": "Settings for the workspace's VCS repository"
},
"working-directory": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The directory to execute commands in",
"title": "Working-Directory"
}
},
"title": "WorkspaceParams",
"type": "object"
}
},
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"organization": {
"title": "Organization",
"type": "string"
},
"params": {
"anyOf": [
{
"$ref": "#/$defs/WorkspaceParams"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"organization",
"name"
],
"title": "create_workspaceArguments",
"type": "object"
}
You must be authenticated.
Other Tools from terraform-cloud-mcp
- apply_run
- cancel_run
- create_organization
- create_run
- create_workspace
- delete_organization
- delete_workspace
- discard_run
- force_cancel_run
- force_execute_run
- force_unlock_workspace
- get_account_details
- get_organization_details
- get_organization_entitlements
- get_run_details
- get_workspace_details
- list_organizations
- list_runs_in_organization
- list_runs_in_workspace
- list_workspaces
- lock_workspace
- safe_delete_workspace
- unlock_workspace
- update_organization
- update_workspace
Related Tools
- @severity1/terraform-cloud-mcp
- @severity1/terraform-cloud-mcp
- @thrashr888/terraform-mcp-server
- @thrashr888/terraform-mcp-server
- @AzBuilder/mcp-server-terrakube