create_organization
Create a new organization in Terraform Cloud to manage workspaces and teams, establishing the foundation for infrastructure management.
Instructions
Create a new organization in Terraform Cloud
Creates a new organization with the given name and email, allowing workspaces and teams to be created within it. This is the first step in setting up a new environment in Terraform Cloud.
API endpoint: POST /organizations
Args: name: The name of the organization (required) email: Admin email address (required) params: Additional organization settings: - collaborator_auth_policy: Authentication policy (password or two_factor_mandatory) - session_timeout: Session timeout after inactivity in minutes - session_remember: Session total expiration time in minutes - cost_estimation_enabled: Whether to enable cost estimation for workspaces - default_execution_mode: Default workspace execution mode (remote, local, agent) - aggregated_commit_status_enabled: Whether to aggregate VCS status updates - speculative_plan_management_enabled: Whether to auto-cancel unused speculative plans - assessments_enforced: Whether to enforce health assessments for all workspaces - allow_force_delete_workspaces: Whether to allow deleting workspaces with resources - default_agent_pool_id: Default agent pool ID (required when using agent mode)
Returns: The created organization details including ID and created timestamp
See: docs/tools/organization.md for reference documentation
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| Yes | |||
| params | No |
Implementation Reference
- The async handler function that implements the core logic for creating a Terraform Cloud organization. It validates inputs using Pydantic models, constructs the API payload, and performs the POST request to the /organizations endpoint.
@handle_api_errors async def create_organization( name: str, email: str, params: Optional[OrganizationParams] = None ) -> APIResponse: """Create a new organization in Terraform Cloud Creates a new organization with the given name and email, allowing workspaces and teams to be created within it. This is the first step in setting up a new environment in Terraform Cloud. API endpoint: POST /organizations Args: name: The name of the organization (required) email: Admin email address (required) params: Additional organization settings: - collaborator_auth_policy: Authentication policy (password or two_factor_mandatory) - session_timeout: Session timeout after inactivity in minutes - session_remember: Session total expiration time in minutes - cost_estimation_enabled: Whether to enable cost estimation for workspaces - default_execution_mode: Default workspace execution mode (remote, local, agent) - aggregated_commit_status_enabled: Whether to aggregate VCS status updates - speculative_plan_management_enabled: Whether to auto-cancel unused speculative plans - assessments_enforced: Whether to enforce health assessments for all workspaces - allow_force_delete_workspaces: Whether to allow deleting workspaces with resources - default_agent_pool_id: Default agent pool ID (required when using agent mode) Returns: The created organization details including ID and created timestamp See: docs/tools/organization.md for reference documentation """ # Extract parameters from the params object if provided param_dict = params.model_dump(exclude_none=True) if params else {} # Create request using Pydantic model with defaults request = OrganizationCreateRequest(name=name, email=email, **param_dict) # Create API payload using utility function payload = create_api_payload(resource_type="organizations", model=request) # Make the API request return await api_request("organizations", method="POST", data=payload) - terraform_cloud_mcp/server.py:78-78 (registration)Registers the create_organization function as an MCP tool with write permissions (enabled unless read-only mode). The write_tool_config includes annotations for readOnlyHint: False.
mcp.tool(**write_tool_config)(organizations.create_organization) - Pydantic model OrganizationCreateRequest defines the input schema for the create organization tool, requiring name and email fields, and inheriting optional organization parameters from BaseOrganizationRequest.
class OrganizationCreateRequest(BaseOrganizationRequest): """Request model for creating a Terraform Cloud organization. Validates and structures the request according to the Terraform Cloud API requirements for creating organizations. Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/organizations#create-an-organization Note: This inherits all configuration fields from BaseOrganizationRequest while making name and email required. See: docs/models/organization.md for reference """ # Override name and email to make them required for creation name: str = Field(..., description="Name of the organization") email: str = Field(..., description="Admin email address") - Pydantic model OrganizationParams provides optional parameters passed to the create_organization handler, inheriting all configurable fields from BaseOrganizationRequest such as session timeouts, auth policies, and execution modes.
class OrganizationParams(BaseOrganizationRequest): """Parameters for organization operations without routing fields. This model provides all optional parameters that can be used when creating or updating organizations, reusing the field definitions from BaseOrganizationRequest. Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/organizations Note: All fields are inherited from BaseOrganizationRequest. See: docs/models/organization.md for reference """ # Inherits model_config and all fields from BaseOrganizationRequest - Base Pydantic model BaseOrganizationRequest defines all configurable fields for organizations, used by OrganizationCreateRequest and OrganizationParams for input validation and serialization.
class BaseOrganizationRequest(APIRequest): """Base class for organization create and update requests with common fields. This includes all fields that are commonly used in request payloads for the organization creation and update APIs. Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/organizations Note: This class inherits model_config from APIRequest -> BaseModelConfig See: docs/models/organization.md for fields 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 organization", min_length=3, pattern=r"^[a-z0-9][-a-z0-9_]*[a-z0-9]$", ) email: Optional[str] = Field( None, # No alias needed as field name matches API field name description="Admin email address", pattern=r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$", ) session_timeout: Optional[int] = Field( 20160, alias="session-timeout", description="Session timeout after inactivity in minutes", ge=1, le=43200, # 30 days in minutes ) session_remember: Optional[int] = Field( 20160, alias="session-remember", description="Session expiration in minutes", ge=1, le=43200, # 30 days in minutes ) collaborator_auth_policy: Optional[Union[str, CollaboratorAuthPolicy]] = Field( CollaboratorAuthPolicy.PASSWORD, alias="collaborator-auth-policy", description="Authentication policy", ) cost_estimation_enabled: Optional[bool] = Field( False, alias="cost-estimation-enabled", description="Whether cost estimation is enabled for all workspaces", ) send_passing_statuses_for_untriggered_speculative_plans: Optional[bool] = Field( False, alias="send-passing-statuses-for-untriggered-speculative-plans", description="Whether to send VCS status updates for untriggered plans", ) aggregated_commit_status_enabled: Optional[bool] = Field( True, alias="aggregated-commit-status-enabled", description="Whether to aggregate VCS status updates", ) speculative_plan_management_enabled: Optional[bool] = Field( True, alias="speculative-plan-management-enabled", description="Whether to enable automatic cancellation of plan-only runs", ) owners_team_saml_role_id: Optional[str] = Field( None, alias="owners-team-saml-role-id", description="SAML only - the name of the 'owners' team", ) assessments_enforced: Optional[bool] = Field( False, alias="assessments-enforced", description="Whether to compel health assessments for all eligible workspaces", ) allow_force_delete_workspaces: Optional[bool] = Field( False, alias="allow-force-delete-workspaces", description="Whether workspace admins can delete workspaces with resources", ) default_execution_mode: Optional[Union[str, ExecutionMode]] = Field( ExecutionMode.REMOTE, alias="default-execution-mode", description="Default execution mode", ) default_agent_pool_id: Optional[str] = Field( None, alias="default-agent-pool-id", description="The ID of the agent pool (required when default_execution_mode is 'agent')", )