# Terraform Cloud (HCP) MCP > Terraform Cloud (HCP) allows your AI agent to manage your entire infrastructure lifecycle using natural language. You can list organizations, create projects, trigger runs, and extract specific state outputs directly from the cloud without opening a dashboard. It puts high-level governance controls and detailed run monitoring right into your chat window. ## Overview - **Category:** ship-it - **Price:** Free - **Tags:** infrastructure-as-code, provisioning, workspace-management, automation, cloud-ops, state-management ## Description Connecting your Terraform Cloud (HCP) account gives your agent direct control over your Infrastructure as Code (IaC) workflows. Instead of clicking through multiple dashboards, you can now talk to your environment. Your agent handles the complexity of the HCP API, letting you manage everything from high-level governance to minute resource changes. Need to see what changed? You can trigger a run and monitor its progress in real time. Want to enforce compliance? Use policies and variable sets to govern workspaces across organizations. When you connect this MCP via Vinkius, all your cloud environments become accessible through a single point of interaction with any MCP-compatible client. ## Tools ### add_team_user Adds a user to an existing team within your organization. ### add_team_workspace_access Grants specific teams access permissions for a particular workspace. ### apply_run Applies the planned changes from a run, committing them to your infrastructure. ### apply_variable_set_to_workspace Configures a workspace by applying an entire set of defined variables. ### associate_run_task_to_workspace Links a specific run task to a target workspace, ensuring proper execution flow. ### cancel_run Stops an active or pending infrastructure run immediately. ### create_notification_configuration Sets up alerts and notifications for changes happening within a workspace. ### create_organization Establishes an entirely new, top-level organizational boundary in your cloud account. ### create_policy_set Creates a group of governance policies that enforce specific architectural rules. ### create_policy Defines a single, reusable policy to check for compliance or mandate specific configurations. ### create_project Sets up a new container project under an existing organization structure. ### create_registry_module Creates a private, self-contained module that doesn't rely on version control system (VCS) integration. ### create_registry_provider Sets up and manages a private registry provider for resource management. ### create_run_task Creates a specific, repeatable task that must be executed during an infrastructure run. ### create_run Starts a new instance of an infrastructure run, which can generate plans or apply changes. ### create_state_version Saves the current state output as a distinct, historical version for record-keeping. ### create_team Creates a new team unit within your organization for role grouping and access control. ### create_variable_set Defines a collection of variables that can be consistently applied to multiple workspaces. ### create_workspace Initializes a new, dedicated workspace for deploying specific infrastructure components. ### create_workspace_variable Adds a single variable to an existing workspace, allowing custom input parameters. ### destroy_organization Permanently deletes an entire organizational structure and all associated resources. ### discard_run Aborts a run that is currently in progress or has not yet been finalized. ### explorer_query Runs a comprehensive query across multiple workspaces to find specific data points or tags. ### force_unlock_workspace Overrides the normal locking mechanism to make a workspace available for changes when needed. ### get_current_state_version Retrieves the metadata identifying the most recent state version of a given workspace. ### get_plan_json Fetches the detailed JSON output that represents exactly what changes will happen during an apply. ### get_state_version_outputs Retrieves all defined output values from a specific, historical state version of a workspace. ### list_audit_events Pulls a list of critical governance events that occurred within the organization. ### list_organizations Lists all top-level organizations you have access to in your account. ### list_projects Retrieves a list of all projects defined within a specific organization. ### list_teams Lists all established teams and their membership within an organization. ### list_workspaces Shows every workspace that exists inside a designated organization or project. ### lock_workspace Prevents any further changes to a workspace until the lock is explicitly released. ### remove_team_user Removes a specific user from membership in an existing team. ### safe_delete_workspace Initiates the process to safely and permanently delete a workspace, handling dependencies first. ### show_apply Displays detailed information about a past or planned apply action. ### show_organization Retrieves the full metadata and details for a specific organization. ### show_plan Shows detailed information about a generated plan, detailing resource changes before they happen. ### unlock_workspace Releases the lock on a workspace, allowing it to be modified again after an incident or run. ### update_organization Modifies existing details of an organization without recreating it. ### update_team Updates the name, description, or membership of a team unit. ### upload_policy_code Uploads custom code that will be evaluated by your governance policies. ## Prompt Examples **Prompt:** ``` List all organizations I have access to in Terraform Cloud. ``` **Response:** ``` I've found 2 organizations: 'Acme-Corp' and 'Dev-Sandbox'. Which one would you like to explore? ``` **Prompt:** ``` Show me all workspaces in the 'Acme-Corp' organization that have the tag 'production'. ``` **Response:** ``` Found 3 production workspaces: 'vpc-prod' (ws-K9...), 'eks-main' (ws-L2...), and 'rds-cluster' (ws-M5...). ``` **Prompt:** ``` Get the output values for workspace ws-K9j2L8mP1. ``` **Response:** ``` The outputs for 'vpc-prod' are: vpc_id = 'vpc-0a1b2c', public_subnets = ['subnet-1', 'subnet-2'], and region = 'us-east-1'. ``` ## Capabilities ### Manage Organization Structure You can list, create, and delete entire organizations or projects to maintain high-level governance. ### Control Workspace Deployments The agent can manage workspace locks, apply variable sets, and associate run tasks to specific workspaces for deployment control. ### Orchestrate Infrastructure Runs Trigger new runs, plan changes, or discard incomplete plans directly through natural language commands. ### Extract State Data and Policies Retrieve current state versions and pull specific output values to use in downstream analysis or automation scripts. ### Enforce Governance Rules Create policies, set up variable sets, and manage user access controls across teams and organizations. ## Use Cases ### Auditing Compliance Post-Deployment A cloud architect needs proof that all staging environments use approved networking components. They ask their agent to `list_workspaces` in the 'Staging' organization, then run an `explorer_query`, and finally review the results against a set of defined policies. ### Responding to a Broken Service An SRE notices a critical workspace is locked. Instead of logging into the dashboard, they prompt their agent to execute `force_unlock_workspace`. Once unlocked, they can then run `create_run` and apply the fix. ### Building Automated Pipelines A DevOps engineer needs a new service. They ask their agent to first `create_organization`, next `create_project`, set up variables using `create_variable_set`, and finally, trigger the full deployment plan with `create_run`. ### Extracting Secrets for Downstream Use A platform engineer needs a specific ID from a newly deployed VPC. They ask their agent to get the current state version (`get_current_state_version`), retrieve the outputs (`get_state_version_outputs`), and feed that single value into another service's API call. ## Benefits - Manage the entire lifecycle without context switching. You can list organizations, create projects, and manage workspaces—all from your AI client's natural language prompt. - Gain full visibility into state management. Use `get_state_version_outputs` to pull specific output values, allowing you to use those results immediately in a subsequent step or script. - Control deployments precisely. You can run `create_run` and then `show_plan`, giving your agent the necessary details before committing changes with `apply_run`. - Enforce compliance automatically. Use tools like `create_policy` to define rules, making sure that every new deployment adheres to organizational standards before it goes live. - Handle incidents faster than ever. If a workspace is locked up, you don't need to navigate menus; simply ask the agent to execute `force_unlock_workspace` and get back to work. ## How It Works The bottom line is you tell your agent what change needs to happen, and it handles all the complex API interactions required to make it real. 1. Subscribe to this MCP and provide your Terraform Cloud User or Team API Token. 2. Your AI client authenticates the connection, giving it visibility into your cloud environment structure. 3. You simply instruct your agent—for example, 'Plan an update for the production workspace'—and the tool executes the necessary sequence of calls. ## Frequently Asked Questions **How do I check if a workspace is locked using the Terraform Cloud (HCP) MCP?** You can use `list_workspaces` to see the current status. If you need to proceed despite the lock, your agent can execute `force_unlock_workspace`. **Can I retrieve outputs from old state versions with Terraform Cloud (HCP) MCP?** Yes. The tool `get_state_version_outputs` lets you pull specific output values from any historical state version, which is critical for auditing. **Is this MCP safe to use when running destructive commands like destroy on Terraform Cloud (HCP)?** The agent guides the process. Before destruction, you should always use `show_plan` to review exactly what resources will be removed before executing a command. **How does the Terraform Cloud (HCP) MCP handle user access?** You manage access using tools like `add_team_user`, `remove_team_user`, and `add_team_workspace_access` to maintain strict role-based governance. **What if I need to update a team name? Can the Terraform Cloud (HCP) MCP do that?** Yes, you can modify existing team details using the `update_team` tool. This keeps your organization's structure current without manual intervention.