create_workspace_variable
Add Terraform or environment variables to a workspace, optionally marking them as sensitive to protect values.
Instructions
Create a new variable in a workspace.
Creates a new Terraform or environment variable within a workspace. Variables can be marked as sensitive to hide their values.
API endpoint: POST /workspaces/{workspace_id}/vars
Args: workspace_id: The ID of the workspace (format: "ws-xxxxxxxx") key: The variable name/key category: Variable category ("terraform" or "env")
params: Additional variable parameters (optional):
- value: Variable value
- description: Description of the variable
- hcl: Whether the value is HCL code (terraform variables only)
- sensitive: Whether the variable value is sensitiveReturns: The created variable with its configuration and metadata
See: docs/tools/variables.md#create-workspace-variable for reference documentation
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| workspace_id | Yes | ||
| key | Yes | ||
| category | Yes | ||
| params | No |
Implementation Reference
- The async handler function implementing the core logic for creating a workspace variable via Terraform Cloud API, using Pydantic models for input validation and API payload construction.
@handle_api_errors async def create_workspace_variable( workspace_id: str, key: str, category: str, params: Optional[WorkspaceVariableParams] = None, ) -> APIResponse: """Create a new variable in a workspace. Creates a new Terraform or environment variable within a workspace. Variables can be marked as sensitive to hide their values. API endpoint: POST /workspaces/{workspace_id}/vars Args: workspace_id: The ID of the workspace (format: "ws-xxxxxxxx") key: The variable name/key category: Variable category ("terraform" or "env") params: Additional variable parameters (optional): - value: Variable value - description: Description of the variable - hcl: Whether the value is HCL code (terraform variables only) - sensitive: Whether the variable value is sensitive Returns: The created variable with its configuration and metadata See: docs/tools/variables.md#create-workspace-variable for reference documentation """ param_dict = params.model_dump(exclude_none=True) if params else {} request = WorkspaceVariableCreateRequest( workspace_id=workspace_id, key=key, category=VariableCategory(category), **param_dict, ) payload = create_api_payload( resource_type="vars", model=request, exclude_fields={"workspace_id"} ) return await api_request( f"workspaces/{workspace_id}/vars", method="POST", data=payload ) - Pydantic model defining optional parameters (value, description, hcl, sensitive) for workspace variable creation, used in the tool handler for input schema and validation.
class WorkspaceVariableParams(APIRequest): """Parameters for workspace variable operations without routing fields. This model provides all optional parameters for creating or updating workspace variables, separating configuration parameters from routing information like workspace ID and variable ID. Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/workspace-variables See: docs/models/variables.md for reference """ key: Optional[str] = Field( None, description="Variable name/key", min_length=1, max_length=255, ) value: Optional[str] = Field( None, description="Variable value", max_length=256000, ) description: Optional[str] = Field( None, description="Description of the variable", max_length=512, ) category: Optional[VariableCategory] = Field( None, description="Variable category (terraform or env)", ) hcl: Optional[bool] = Field( None, description="Whether the value is HCL code (only valid for terraform variables)", ) sensitive: Optional[bool] = Field( None, description="Whether the variable value is sensitive", ) - Enum defining valid category values ('terraform', 'env') for workspace variables, used in input validation.
class VariableCategory(str, Enum): """Variable category options for workspace variables. Defines the type of variable: - TERRAFORM: Terraform input variables available in configuration - ENV: Environment variables available during plan/apply operations Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/workspace-variables See: docs/models/variables.md for reference """ TERRAFORM = "terraform" ENV = "env" - terraform_cloud_mcp/server.py:126-126 (registration)Tool registration in the FastMCP server using the create_workspace_variable handler function, configured with write permissions.
mcp.tool(**write_tool_config)(variables.create_workspace_variable)