Connect to the remote Terraform MCP server

The remote Terraform Model Context Protocol (MCP) server is a HashiCorp-hosted MCP server that connects your AI clients and AI coding assistants to HCP Terraform. Authenticate with an HCP Terraform API token to give your AI model access to the public Terraform Registry, your private registry, and your HCP Terraform organizations, with no Docker, binary, or server to operate.

Beta feature

Beta functionality is stable but possibly incomplete and subject to change. We strongly discourage using beta features in production deployments.

Introduction

The remote Terraform MCP server runs the same Terraform MCP server that you can deploy locally or host yourself. Refer to Deploy the Terraform MCP server locally and Deploy a self-hosted Terraform MCP server for information on those deployment options.

The remote Terraform MCP server differs from those deployment options in the following ways:

HashiCorp operates, updates, and scales the server. HashiCorp deploys each Terraform MCP server release to the remote server on the day of the release.
Using the remote server does not change your resources under management (RUM) usage or your HCP Terraform plan entitlements.
The server requires an HCP Terraform API token on every request, including requests to the public registry tools. The server can only perform actions that your token has permission to perform.

Refer to Deploy the Terraform MCP server for a comparison of the deployment options.

Available tools

The remote Terraform MCP server provides the tools in the registry, registry-private, and terraform toolsets. Every tool runs with the permissions of the token that your client sends. Refer to Terraform MCP server reference for a description of each tool.

The remote server does not provide destructive operations. The following tools are not available:

The create_run tool only supports the default run types. You cannot create auto-approved or destroy runs. Refer to Run type options for more information. To use destructive operations, deploy a self-hosted server and set ENABLE_TF_OPERATIONS to true. Refer to Deploy a self-hosted Terraform MCP server for instructions.

The server generates outputs and recommendations dynamically. Always review changes before you apply them to your infrastructure.

Limitations

The remote Terraform MCP server has the following limitations:

The server only connects to HCP Terraform organizations in the United States. It does not support Terraform Enterprise or HCP Europe organizations. To use the Terraform MCP server with Terraform Enterprise, refer to Deploy a self-hosted Terraform MCP server.
HCP Terraform does not act as an OAuth provider, so you must add an API token to your client configuration.
HCP Terraform does not provide settings to turn off the remote server or individual toolsets for your organization.
You cannot change the server configuration, such as the enabled toolsets or environment variables. To control the server configuration, deploy a self-hosted server.
The server limits each session to 5 requests per second, with bursts of up to 10 requests. The server also applies a global limit across all sessions. When a request exceeds a limit, the tool call returns a tool error that says the request is rate limited, instead of an HTTP 429 response.

Connection workflow

Complete the following steps to connect to the remote Terraform MCP server:

Requirements

You must have the following to connect to the remote Terraform MCP server:

An HCP Terraform account on any plan, including Free, during the beta.
An HCP Terraform user or team API token. Refer to Create an API token for more information.
An AI client that supports MCP servers over HTTP and lets you send a custom HTTP header with each request.
Network access to https://mcp.terraform.io from the machine that runs your AI client.

Create an API token

You can authenticate with an HCP Terraform user API token or team API token. The permissions of the token determine what your AI model can access and do.

Create a user or team API token. Refer to the following guides for instructions:
- Create a user API token
- Create a team API token
Copy the token. HCP Terraform only displays the token once.
Store the token according to your organization's security policies. Do not commit a configuration file that contains your token to version control.

The MCP server does not restrict token types, but HCP Terraform limits what each token type can do. For example, an organization API token cannot start runs, so run tools fail when your client sends an organization token. Refer to Access levels for the permissions of each token type.

Warning

A user API token authenticates as you, so it can reach every HCP Terraform organization that your account belongs to, with the same permissions that you have. Before you ask your AI model to perform write, plan, apply, or state operations, confirm which organization the model is targeting.

How the server handles your token

The remote Terraform MCP server reads your token from the Authorization bearer header. The server also accepts the token in a TFE_TOKEN header, but the Authorization header takes precedence when a request includes both.

The server rejects the following requests:

Requests that pass the token in a query parameter.
Requests that specify a Terraform address in a header or query parameter.

The remote Terraform MCP server always connects to HCP Terraform. The server does not store or log your token. The server uses the token only for the duration of a request to call HCP Terraform and private registry APIs. Refer to Remote Terraform MCP server security for more information.

Configure your AI client

Add the remote Terraform MCP server URL and an Authorization header that contains your API token to your AI client's MCP configuration. Replace <YOUR_HCP_TERRAFORM_TOKEN> with the token that you created.

Add the following configuration to your .bob/mcp.json file:

{
  "mcpServers": {
    "terraform": {
      "url": "https://mcp.terraform.io/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_HCP_TERRAFORM_TOKEN>"
      }
    }
  }
}

To use the server in a project, add the following configuration to the .cursor/mcp.json file in your project. To use the server in all projects, add it to the ~/.cursor/mcp.json file instead:

{
  "mcpServers": {
    "terraform": {
      "url": "https://mcp.terraform.io/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_HCP_TERRAFORM_TOKEN>"
      }
    }
  }
}

Refer to Cursor's MCP documentation for more information.

To use the server globally, add the following configuration to the ~/.kiro/settings/mcp.json file. To use the server in a workspace, add it to the .kiro/settings/mcp.json file instead:

{
  "mcpServers": {
    "terraform": {
      "url": "https://mcp.terraform.io/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_HCP_TERRAFORM_TOKEN>"
      }
    }
  }
}

If you are not signed in to the Kiro CLI, run kiro-cli login. Then run the following command to verify the integration. The output lists the terraform server.

$ kiro-cli mcp list

Refer to Kiro's MCP configuration documentation for more information.

Add the following configuration to your opencode.json file:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "terraform": {
      "type": "remote",
      "url": "https://mcp.terraform.io/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer <YOUR_HCP_TERRAFORM_TOKEN>"
      }
    }
  }
}

To add the server to a workspace, add the following configuration to the .vscode/mcp.json file. To add the server to your user configuration, run the MCP: Open User Configuration command and add the following configuration:

{
  "servers": {
    "terraform": {
      "type": "http",
      "url": "https://mcp.terraform.io/mcp",
      "headers": {
        "Authorization": "Bearer ${input:hcp-terraform-token}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "hcp-terraform-token",
      "description": "HCP Terraform API token",
      "password": true
    }
  ]
}

Visual Studio Code prompts for your token the first time the server starts and stores it securely. To use the Terraform MCP server tools, open GitHub Copilot Chat in agent mode.

For other AI clients, add a remote MCP server that uses https://mcp.terraform.io/mcp as the URL and sends the Authorization: Bearer <YOUR_HCP_TERRAFORM_TOKEN> header. Refer to your AI client's documentation for the configuration format.

After you update the configuration, restart or reload your AI client so that it connects to the terraform server.

Verify the connection

Ask your AI model which HCP Terraform user it is authenticated as. The model uses the whoami tool to return the username and email address associated with your token. Refer to Terraform MCP server reference for more information.

Connection errors

The following errors can occur when you connect to the remote Terraform MCP server.

Token sent in a query parameter

The server returns the following error:

Terraform token should not be provided in query parameters for security reasons, use the Authorization header

Your client sent the token as a query parameter. Send the token in the Authorization: Bearer header instead.

Terraform address in the request

The server returns the following error:

Cannot specify Terraform address via header or query parameter

Your client configuration sets a Terraform address, such as TFE_ADDRESS. Remove the address from your client configuration. The remote Terraform MCP server always connects to HCP Terraform.

Missing bearer token

The server returns the following error:

Authorization bearer token is required

Your client did not send an Authorization: Bearer header. The remote Terraform MCP server requires a token on every request, including requests to the public registry tools. Add the header to your client configuration.

Unauthorized token

The server returns the following error:

Terraform token is unauthorized

HCP Terraform rejected your token. The token may be expired or revoked, or it may belong to an HCP Europe organization. Create a new HCP Terraform API token and update your client configuration.

Rate limit exceeded

The server returns one of the following errors:

rate limit exceeded: too many requests from this session
rate limit exceeded: too many requests globally

The first error means that your client sent more than 5 requests per second in a session. The second error means that the server reached its global limit across all sessions. In both cases, wait a moment and then retry the request.

Next steps

Start prompting your AI model to create Terraform configuration. Refer to Prompt an AI model for guidance on effective prompting techniques.
To use the Terraform MCP server with Terraform Enterprise or to control the server configuration, refer to Deploy a self-hosted Terraform MCP server.