Connect Hashicorp Terraform Cloud to Claude: Manage Runs and Policies

If your team uses ChatGPT, check out our guide on connecting Hashicorp Terraform Cloud to ChatGPT or explore our broader architectural overview on connecting Hashicorp Terraform Cloud to AI Agents.

Large Language Models are excellent at generating HashiCorp Configuration Language (HCL). But writing infrastructure-as-code is only half the battle. To actually automate DevOps operations, your AI agents need access to the deployment environment. They need to be able to trigger runs, evaluate policy checks, read state versions, and inject variables directly into HashiCorp Terraform Cloud.

Giving Claude read and write access to your Terraform Cloud organization requires a Model Context Protocol (MCP) server. This server acts as the translation layer, exposing complex infrastructure operations as discrete, predictable tools that the LLM can call. You can build and maintain this translation layer from scratch, or you can use a managed integration layer to dynamically generate a secure, authenticated MCP server URL.

This guide breaks down exactly how to use Truto to generate a managed MCP server for HashiCorp Terraform Cloud, connect it natively to Claude, and execute complex infrastructure-as-code workflows using natural language.

The Engineering Reality of the HashiCorp Terraform Cloud API

A custom MCP server is a self-hosted integration layer that translates an LLM's tool calls into REST API requests. If you decide to build a custom MCP server for Terraform Cloud, you own the entire API lifecycle. You are not just dealing with simple CRUD operations - you are interfacing with a strictly governed, stateful orchestration engine.

Here are the specific challenges you will face when mapping the Terraform Cloud API to an AI agent framework:

The JSON:API Specification Terraform Cloud's API strictly follows the vnd.api+json specification (JSON:API). This means every payload requires a highly nested structure consisting of data, type, attributes, and relationships. LLMs struggle to reliably generate these deeply nested relationships from scratch without hallucinating schema properties. A managed MCP server abstracts this away by flattening the input namespace, allowing Claude to pass simple parameters while the proxy layer constructs the compliant JSON:API request body.

The Asynchronous Run State Machine Creating a run in Terraform Cloud does not immediately apply your infrastructure changes. A run enters a complex state machine: it queues, plans, evaluates Sentinel policies, requires manual or automated confirmation, and finally applies. An AI agent cannot just "fire and forget" an apply request. It must poll the run status, read the execution plan logs, and explicitly trigger the apply phase if the workspace is not set to auto-apply. Building this logic into hand-coded MCP tools requires extensive error handling.

Workspace Locking and Race Conditions Terraform workspaces are locked during runs to prevent state corruption. If an LLM attempts to update a workspace variable or force a run while another operation is in progress, the API returns a 409 Conflict. Hand-coded servers often fail silently here. A normalized toolset surfaces these lock states immediately, allowing the model to decide whether to wait or issue a force-unlock command.

Strict Rate Limiting and Backoff Delegation HashiCorp enforces strict API rate limits to maintain platform stability. Truto does not retry, throttle, or apply backoff on rate limit errors. When an upstream API returns HTTP 429, Truto passes that error directly to the caller. Truto normalizes upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The caller (your agent framework or Claude client) is strictly responsible for implementing its own retry and exponential backoff logic. Do not assume the integration layer will absorb these limits for you.

Instead of building this infrastructure from scratch, you can use Truto. Truto normalizes authentication, pagination, and JSON:API payloads, exposing Terraform Cloud's endpoints as ready-to-use MCP tools.

How to Generate a Terraform Cloud MCP Server

Truto dynamically generates MCP tools based on the API documentation and resources available for an integrated account. Once you have connected a HashiCorp Terraform Cloud account, you can generate a secure server URL.

You can create this server through the Truto UI or programmatically via the REST API.

Method 1: Via the Truto UI

1. Log into your Truto dashboard and navigate to the integrated account page for your HashiCorp Terraform Cloud connection.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Define your configuration. You can filter by HTTP methods (e.g., read-only operations) or restrict access via tags.
5. Copy the generated MCP server URL (e.g., https://api.truto.one/mcp/abc123xyz...).

Method 2: Via the Truto API

For teams building automated provisioning pipelines, you can generate an MCP server dynamically by making an API request.

Endpoint: POST /integrated-account/:id/mcp

{
  "name": "Terraform Cloud SecOps Agent",
  "config": {
    "methods": ["read", "write", "custom"]
  },
  "expires_at": "2026-12-31T23:59:59Z"
}

The API provisions a cryptographically secure token and returns a ready-to-use endpoint:

{
  "id": "mcp_srv_98765",
  "name": "Terraform Cloud SecOps Agent",
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6g7h8...",
  "expires_at": "2026-12-31T23:59:59Z"
}

This URL is self-contained. It handles the JSON-RPC 2.0 protocol and routes all requests to your specific Terraform Cloud tenant.

How to Connect the MCP Server to Claude

Once you have your MCP server URL, you must register it with your Claude client. You can do this through the Claude user interface or by modifying the configuration file directly.

Method A: Via the Claude UI

If you are using the Claude web interface or Enterprise features that support UI-based connector management:

1. In Claude, navigate to Settings -> Integrations -> Add MCP Server.
2. Give your connection a descriptive name, like "Terraform Cloud Operations".
3. Paste the Truto MCP URL into the Server URL field.
4. Click Add. Claude will immediately perform a handshake, discover the available tools, and make them available to your current session.

Method B: Via Manual Configuration File

For developers using the Claude Desktop app, you can configure the connection manually by updating your claude_desktop_config.json file. Because Truto provides a hosted HTTP endpoint, you use the standard Server-Sent Events (SSE) transport adapter.

Open your configuration file (located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows) and add the following JSON:

{
  "mcpServers": {
    "terraform-cloud": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/a1b2c3d4e5f6g7h8..."
      ]
    }
  }
}

Restart Claude Desktop. The client will establish a persistent connection to the server, and the Terraform Cloud tools will appear in your prompt interface.

Hero Tools for HashiCorp Terraform Cloud

By leveraging the integration's native definitions, Truto translates Terraform Cloud resources into discrete tools. Here are the most powerful tools your AI agent can use to manage infrastructure.

1. create_a_hashicorp_terraform_cloud_run

This is the core execution tool. It triggers a new run in a specific workspace. You must provide the workspace ID. It returns the run ID, status, and related configuration data.

"Trigger a new run in the production-k8s-cluster workspace. Let me know the run ID so we can track the plan status."

2. hashicorp_terraform_cloud_runs_apply

Creating a run only initiates a plan (unless auto-apply is enabled). Once a plan is reviewed and policy checks pass, the run enters a paused state. This tool instructs Terraform Cloud to proceed with the actual infrastructure modifications.

"The plan for run-12345 looks clean and all policy checks passed. Go ahead and apply the run."

3. hashicorp_terraform_cloud_workspaces_lock

Before executing sensitive operations or emergency rollbacks, you may need to manually lock a workspace to prevent other CI/CD systems or users from triggering concurrent runs.

"Lock the eu-west-database workspace immediately and give me confirmation. We need to halt all deployments while we investigate the networking alert."

4. list_all_hashicorp_terraform_cloud_policy_checks

HashiCorp's Sentinel and OPA integrations execute policy checks between the plan and apply phases. This tool allows the agent to audit exactly which policies failed during a run, retrieving the specific rules and error messages.

"Check the policy evaluation results for run-98765. Tell me which specific security rules failed and what the error message was."

5. update_a_hashicorp_terraform_cloud_variable_by_id

Workspaces rely on variables for dynamic configuration. This tool allows the agent to update specific variables (like instance counts or feature flags) without requiring a developer to manually edit the UI or push a commit.

"Update the instance_count variable in the web-frontend workspace to 5. The variable ID is var-xyz123."

6. get_single_hashicorp_terraform_cloud_run_by_id

Because Terraform runs are asynchronous, agents must check the status of a run to determine if it is planning, policy-checking, applying, or errored. This tool fetches the current execution state.

"Get the current status of run-44556. Is it still planning, or is it waiting for confirmation to apply?"

To view the complete schema details, JSON:API relationship mappings, and the full inventory of available endpoints, check out the Hashicorp Terraform Cloud integration page.

Workflows in Action

Providing an LLM with discrete tools unlocks powerful, autonomous infrastructure operations. Here are two real-world workflows demonstrating how an AI agent uses these tools in sequence to solve DevOps problems.

Workflow 1: Investigating and Remediating a Blocked Deployment

A developer reports that their recent commit to the networking repository has not deployed. The AI agent acts as a Level 1 Site Reliability Engineer to investigate the failure and remediate it.

"Investigate why the latest run in the core-networking workspace is stuck. If it is a soft-failed policy check regarding tagging, override the policy and apply the run."

Agent Execution Steps:

1. Find the workspace runs: The agent calls list_all_hashicorp_terraform_cloud_runs passing the workspace ID to find the most recent active run.
2. Check run status: The agent calls get_single_hashicorp_terraform_cloud_run_by_id and discovers the run is stuck in a policy_override state.
3. Audit the failure: The agent calls list_all_hashicorp_terraform_cloud_policy_checks for the specific run ID. It reads the result and confirms the failure is due to a soft-mandatory tagging rule.
4. Override the policy: The agent calls hashicorp_terraform_cloud_policy_checks_override to acknowledge and bypass the soft-mandatory failure.
5. Execute the apply: With the policy cleared, the agent calls hashicorp_terraform_cloud_runs_apply to finalize the deployment.

Result: The user receives a detailed summary explaining that the deployment was blocked by a tagging policy, that the agent overrode the soft warning, and that the infrastructure apply is now executing.

Workflow 2: Emergency Scaling and Variable Management

During a traffic spike, a DevOps engineer needs to rapidly scale up web instances across multiple regions. Instead of logging into the UI and manually editing variables in multiple workspaces, they use natural language.

"We are seeing a traffic spike. Update the max_nodes variable in the eu-frontend workspace to 20, lock the workspace, and trigger a new run to scale the infrastructure."

Agent Execution Steps:

1. Lock the environment: The agent calls hashicorp_terraform_cloud_workspaces_lock to ensure no automated systems attempt to deploy concurrently.
2. Locate the variable: The agent calls list_all_hashicorp_terraform_cloud_workspace_variables to find the exact ID for the max_nodes variable.
3. Update the value: The agent calls update_a_hashicorp_terraform_cloud_variable_by_id and changes the value to 20.
4. Unlock the environment: The agent calls hashicorp_terraform_cloud_workspaces_unlock to permit new deployments.
5. Execute the scale: The agent calls create_a_hashicorp_terraform_cloud_run to trigger a new run, which will pick up the updated max_nodes value and provision the new instances.

Result: The user is provided with the new run ID to track the scale-up event, and the variable is safely updated across the environment.

Security and Access Control

Giving an AI model access to a production Terraform Cloud environment requires strict boundaries. If an agent hallucinates a destructive action (like deleting a workspace), your business is at risk. MCP servers generated by Truto provide robust access controls:

• Method Filtering: When creating the server, you can restrict operations to safe methods. Setting methods: ["read"] ensures the LLM can only query states, list runs, and fetch variables. It cannot trigger an apply or update a configuration.
• Tag Filtering: You can restrict the MCP server to only expose tools relevant to specific resources, such as policies or workspaces, preventing the agent from accessing user management endpoints.
• API Token Authentication: By setting require_api_token_auth: true, the MCP server URL itself is not enough to grant access. The connecting client must also supply a valid Truto API token, adding an essential layer of zero-trust security.
• Time-to-Live (TTL): The expires_at configuration creates temporary access windows. You can spin up an MCP server with write access specifically for a 2-hour deployment window, after which the token automatically invalidates, and access is revoked.

The Shift to Agentic Infrastructure

Integrating HashiCorp Terraform Cloud with Claude transforms how operations teams interact with their environments. You no longer have to navigate complex UIs, decipher nested JSON:API payloads in curl commands, or build fragile, hand-coded chatops scripts.

By leveraging a managed MCP server, you offload the complexities of cursor pagination, HTTP 429 backoff delegation, and payload normalization. The AI framework handles the intent, and the integration layer handles the protocol.

:::cta{buttonText="Talk to us" buttonUrl="https://cal.com/truto/partner-with-truto"} Stop building boilerplate API connectors. Generate secure MCP servers for HashiCorp Terraform Cloud, Salesforce, HubSpot, and 100+ other enterprise platforms in minutes. :::