create_workspace
Create a new Terraform Cloud workspace for managing infrastructure configurations. Define execution modes, Terraform versions, VCS repositories, and custom triggers to isolate and automate infrastructure workflows.
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 triggers
Returns: 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 |
|---|---|---|---|
| name | Yes | ||
| organization | Yes | ||
| params | No |
Implementation Reference
- The handler function that implements the core logic of the 'create_workspace' tool. It constructs a Pydantic request model from inputs, generates the API payload, and performs the POST request to the Terraform Cloud workspaces endpoint.@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' function as an MCP tool using FastMCP, with configuration from write_tool_config which enables it unless in read-only mode.mcp.tool(**write_tool_config)(workspaces.create_workspace)
- Pydantic model used internally to validate and structure the create workspace request payload. Inherits from BaseWorkspaceRequest which defines all optional params fields.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", )
- Pydantic model for the optional 'params' argument in create_workspace function signature, providing type validation for all configurable workspace attributes.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 """
- terraform_cloud_mcp/server.py:39-42 (registration)Configuration dictionary used when registering write tools like create_workspace, controlling enablement based on read-only mode and adding MCP annotations.write_tool_config = { "enabled": not read_only_mode, "annotations": {"readOnlyHint": False} }