create_workspace
Create an isolated Terraform Cloud workspace to manage infrastructure with variables, state files, and run histories for specific configurations.
Instructions
Create a new workspace in an organization.
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 triggersReturns: The created workspace data including configuration, settings and metadata
See: docs/tools/workspace.md for reference documentation
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| organization | Yes | ||
| name | Yes | ||
| params | No |
Implementation Reference
- The main handler function that executes the create_workspace tool. It constructs the API payload using Pydantic models and makes a POST request to the Terraform Cloud API to create a new workspace.
@handle_api_errors async def create_workspace( organization: str, name: str, params: Optional[WorkspaceParams] = None ) -> APIResponse: """Create a new workspace in an organization. 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.md for reference documentation """ param_dict = params.model_dump(exclude_none=True) if params else {} request = WorkspaceCreateRequest(organization=organization, name=name, **param_dict) payload = create_api_payload( resource_type="workspaces", model=request, exclude_fields={"organization"} ) return await api_request( f"organizations/{organization}/workspaces", method="POST", data=payload ) - terraform_cloud_mcp/server.py:55-55 (registration)Registers the create_workspace handler as an MCP tool using FastMCP, with write_tool_config enabling it for non-read-only mode.
mcp.tool(**write_tool_config)(workspaces.create_workspace) - Pydantic model used for optional params in create_workspace function signature, inheriting all workspace configuration fields from BaseWorkspaceRequest.
class WorkspaceParams(BaseWorkspaceRequest): """Parameters for workspace operations without routing fields. This model provides all optional parameters for creating or updating workspaces, reusing field definitions from BaseWorkspaceRequest. It separates configuration parameters from routing information like organization and workspace name. Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/workspaces Note: When updating a workspace, use this model to specify only the attributes you want to change. Unspecified attributes retain their current values. All fields are inherited from BaseWorkspaceRequest. See: docs/models/workspace.md for reference """ # Inherits model_config and all fields from BaseWorkspaceRequest - Pydantic model used internally to construct the API request payload for workspace creation.
class WorkspaceCreateRequest(BaseWorkspaceRequest): """Request model for creating a Terraform Cloud workspace. Validates and structures the request according to the Terraform Cloud API requirements for creating workspaces. Extends BaseWorkspaceRequest with required fields for creation. Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/workspaces#create-a-workspace Note: This inherits all configuration fields from BaseWorkspaceRequest while making organization and name required. See: docs/models/workspace.md for reference """ # Override organization and name to make them required for creation organization: str = Field( ..., # No alias needed as field name matches API field name description="The name of the organization to create the workspace in", ) name: str = Field( ..., # No alias needed as field name matches API field name description="Name of the workspace", ) - Base Pydantic model defining all common configuration fields for workspaces, used by WorkspaceParams and WorkspaceCreateRequest.
class BaseWorkspaceRequest(APIRequest): """Base class for workspace create and update requests with common fields. This includes common fields used in request payloads for workspace creation and update APIs, providing a foundation for more specific workspace models. Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/workspaces Note: This class inherits model_config from APIRequest -> BaseModelConfig and provides default values for most fields based on Terraform Cloud API defaults. See: docs/models/workspace.md for detailed field descriptions and usage examples """ # Fields common to both create and update requests with API defaults from docs name: Optional[str] = Field( None, # No alias needed as field name matches API field name description="Name of the workspace", ) description: Optional[str] = Field( None, # No alias needed as field name matches API field name description="Description of the workspace", ) execution_mode: Optional[Union[str, ExecutionMode]] = Field( ExecutionMode.REMOTE, alias="execution-mode", description="How operations are executed", ) agent_pool_id: Optional[str] = Field( None, alias="agent-pool-id", description="The ID of the agent pool" ) assessments_enabled: Optional[bool] = Field( False, alias="assessments-enabled", description="Whether to perform health assessments", ) auto_apply: Optional[bool] = Field( False, alias="auto-apply", description="Whether to automatically apply changes in runs triggered by VCS, UI, or CLI", ) auto_apply_run_trigger: Optional[bool] = Field( False, alias="auto-apply-run-trigger", description="Whether to automatically apply changes initiated by run triggers", ) auto_destroy_at: Optional[str] = Field( None, alias="auto-destroy-at", description="Timestamp when the next scheduled destroy run will occur", ) auto_destroy_activity_duration: Optional[str] = Field( None, alias="auto-destroy-activity-duration", description="Value and units for automatically scheduled destroy runs based on workspace activity", ) file_triggers_enabled: Optional[bool] = Field( True, alias="file-triggers-enabled", description="Whether to filter runs based on file paths", ) working_directory: Optional[str] = Field( None, alias="working-directory", description="The directory to execute commands in", ) speculative_enabled: Optional[bool] = Field( True, alias="speculative-enabled", description="Whether this workspace allows speculative plans", ) terraform_version: Optional[str] = Field( "latest", alias="terraform-version", description="Specifies the version of Terraform to use for this workspace", ) global_remote_state: Optional[bool] = Field( False, alias="global-remote-state", description="Whether to allow all workspaces to access this workspace's state", ) vcs_repo: Optional[Union[VcsRepoConfig, None]] = Field( None, alias="vcs-repo", description="Settings for the workspace's VCS repository", ) allow_destroy_plan: Optional[bool] = Field( True, alias="allow-destroy-plan", description="Whether to allow destruction plans", ) queue_all_runs: Optional[bool] = Field( False, alias="queue-all-runs", description="Whether runs should be queued immediately", ) source_name: Optional[str] = Field( None, alias="source-name", description="Indicates where the workspace settings originated", ) source_url: Optional[str] = Field( None, alias="source-url", description="URL to origin source" ) trigger_prefixes: Optional[List[str]] = Field( None, alias="trigger-prefixes", description="List of paths that trigger runs" ) trigger_patterns: Optional[List[str]] = Field( None, alias="trigger-patterns", description="List of glob patterns that trigger runs", ) setting_overwrites: Optional[Dict[str, bool]] = Field( None, alias="setting-overwrites", description="Specifies attributes that have organization-level defaults", )