Terraform MCP server reference

The Terraform Model Context Protocol (MCP) server reference lists every tool and toolset the server provides, plus the MCP resources, transport protocols, command-line flags, health endpoint, environment variables, and telemetry metrics you use to configure and monitor the server.

Available tools

The Terraform MCP server provides specialized tools that AI models can use to access current Terraform registry information. These tools work automatically when you ask relevant questions, so you don't need to invoke them manually.

To make these tools available to your AI model, deploy the Terraform MCP server or connect to the remote Terraform MCP server.

Toolsets

The server includes the following toolsets:

Toolset	Description
`registry`	Tools for accessing the public registry
`registry-private`	Tools for accessing private registries
`terraform`	Tools for interacting with HCP Terraform and Terraform Enterprise

Add the --toolsets flag to enable or disable these tools when starting the MCP server.

When you start the server without the --toolsets flag, the server enables all toolsets. The server registers the tools in the registry-private and terraform toolsets only when you provide a valid TFE_TOKEN. Some tools in the terraform toolset also require you to set ENABLE_TF_OPERATIONS to true.

You can add the --tools flag instead to enable individual tools by name. You cannot use the --tools flag together with the --toolsets flag. Refer to Command-line flags for more information.

Provider tools

Access comprehensive provider documentation for resources, data sources, functions, and configuration guides.

Tool	Purpose	What it returns
`search_providers`	Find provider documentation by service name	List of available documentation with IDs, titles, and categories
`get_provider_details`	Retrieve complete documentation for a specific provider component	Full documentation content in markdown format
`get_provider_capabilities`	Discover all resource types a provider supports before looking up specific resources	List of resources, data-sources, function names and more
`get_latest_provider_version`	Retrieve the latest version of a specific provider	The latest version of a provider

Example prompt: "How do I configure an AWS S3 bucket with versioning enabled?"

Module tools

Discover and explore community and verified modules from the Terraform registry.

Tool	Purpose	What it returns
`search_modules`	Find modules by name or functionality	Module details including names, descriptions, download counts, and verification status
`get_module_details`	Get comprehensive module information	Complete documentation with inputs, outputs, examples, and submodules
`get_latest_module_version`	Retrieve the latest version of a specific module	The latest version of a module

Example prompt: "Show me modules for deploying a Kubernetes cluster on AWS."

Policy tools

Access Sentinel policies for governance and compliance requirements.

Tool	Purpose	What it returns
`search_policies`	Find Sentinel policies by topic or requirement	Policy listings with IDs, names, and download statistics
`get_policy_details`	Retrieve detailed policy documentation	Policy implementation details and usage instructions

Example prompt: "What Sentinel policies are available for enforcing security best practices?"

Private registry tools

Find private modules and providers in your HCP Terraform or Terraform Enterprise organization. These tools belong to the registry-private toolset.

Tool	Purpose	What it returns
`search_private_modules`	Find private modules in your organization	List of private modules matching search criteria
`get_private_module_details`	Get detailed private module information	Complete module details including inputs, outputs, and examples
`search_private_providers`	Find private providers in your organization	List of private providers matching search criteria
`get_private_provider_details`	Get detailed private provider information	Provider details including usage and version information

Example prompts:

"List all private modules related to AWS"

Identity and organization tools

Identify the authenticated token and list the organizations that the token can access. These tools belong to the terraform toolset.

Tool	Purpose	What it returns
`whoami`	Identify the user or service account that the Terraform token belongs to	Username, email address, and whether the token belongs to a service account
`get_token_permissions`	Get the permissions for the `TFE_TOKEN`	A list of actions you can take
`list_terraform_orgs`	Fetch all Terraform organizations	List of organizations with their details

Project tools

Manage projects in an organization. These tools belong to the terraform toolset.

Tool	Purpose	What it returns
`list_terraform_projects`	Fetch all Terraform projects	List of projects with their metadata
`create_project`	Create a project in an organization	Details of the created project
`get_project`	Fetch detailed information about a project by its ID	Project details including name, description, and default execution mode
`delete_project`	Delete a project by ID. The request fails when the project still contains workspaces or Stacks. `ENABLE_TF_OPERATIONS` must also be set to `true`.	Confirmation of deletion

Team tools

Manage teams and team access in an organization. These tools belong to the terraform toolset.

Tool	Purpose	What it returns
`list_teams`	List teams in an organization, with optional filters for exact team names or a search query	Summary of each team including ID, name, visibility, and member count
`get_team`	Fetch full details for a single team by ID	Team details including members, organization access permissions, and SSO settings
`create_team`	Create a team in an organization	Team ID, name, and visibility
`add_team_member`	Add a single member to a team by username or organization membership ID	Confirmation that the member was added
`grant_team_access`	Grant a team access to a workspace or a project	The created access grant including its ID, team ID, target resource ID, and access level
`delete_team`	Permanently delete a team by ID. `ENABLE_TF_OPERATIONS` must also be set to `true`.	Confirmation of deletion

Workspace tools

Manage workspaces in an organization. These tools belong to the terraform toolset. Some tools require the ENABLE_TF_OPERATIONS environment variable for destructive operations such as deletes, force unlock, and applying, discarding or cancelling runs.

Tool	Purpose	What it returns
`list_workspaces`	Search and list workspaces in an organization	Workspace details including configuration and status
`get_workspace_details`	Get comprehensive workspace information	Complete workspace configuration, variables, and state information
`create_workspace`	Create a new Terraform workspace.	Confirmation of workspace creation. This tool performs a destructive operation
`create_no_code_workspace`	Create a workspace from a no-code module. The tool uses MCP elicitation to collect the required module variables from you.	Details of the created workspace
`update_workspace`	Update workspace configuration.	Updated workspace configuration. This tool performs a potentially destructive operation
`delete_workspace_safely`	Delete workspace if it manages no resources. `ENABLE_TF_OPERATIONS` must also be set to `true`.	Confirmation of deletion
`force_unlock_workspace`	Force unlock a workspace that is stuck in a lock. Requires workspace admin permissions. `ENABLE_TF_OPERATIONS` must also be set to `true`.	Confirmation that the workspace is unlocked

Example prompts:

"Create a new workspace called 'production-app' in my organization"

Run, plan, and apply tools

Create runs and inspect their plans, applies, and comments. These tools belong to the terraform toolset.

Tool	Purpose	What it returns
`list_runs`	List or search runs in a workspace	Run details with optional filtering
`get_run_details`	Get detailed information about a specific run	Complete run information including logs and status
`get_run_comments`	List the comments that users submitted on a run	ID and body text of each comment
`create_run`	Create a new Terraform run	Run creation confirmation with available run types
`action_run`	Perform apply, discard, or cancel operations on runs. `ENABLE_TF_OPERATIONS` must also be set to `true`.	Action confirmation
`get_plan_details`	Fetches detailed metadata about a specific Terraform plan	Plan metadata
`get_plan_logs`	Retrieves the execution logs of a specific Terraform plan	Plan logs as text
`get_plan_json_output`	Retrieves the structured JSON output of a Terraform plan, providing detailed resource changes in a machine-readable format that is easier to parse than plain logs	Plan output in JSON format
`get_apply_details`	Fetches detailed metadata about a specific Terraform apply	Apply metadata
`get_apply_logs`	Retrieves the execution logs of a specific Terraform apply operation	Apply logs as text, or a status message when the apply is still in progress
`get_sentinel_mock`	Export and download Sentinel mock bundle data for a plan	Sentinel mock data that you can use to test policies against plan output

Example prompts:

"Show me all runs for the staging workspace"

State version tools

Inspect the state versions of a workspace. These tools belong to the terraform toolset.

Tool	Purpose	What it returns
`list_state_versions`	List the state versions of a workspace	Summary of each state version including ID, creation time, serial, and Terraform version
`get_state_version`	Retrieve a specific state version, or the latest state version of a workspace	State version details

Policy set tools

Read and attach the policy sets for a workspace. These tools belong to the terraform toolset.

Tool	Purpose	What it returns
`list_workspace_policy_sets`	Get the policy sets attached to a particular workspace	A list of policy sets
`attach_policy_set_to_workspaces`	Attach a policy set to a workspace	Confirmation of attachment

Variable management tools

Manage variables and variable sets across workspaces and organizations.

Tool	Purpose	What it returns
`list_variable_sets`	List all variable sets in an organization	Variable set details and configurations
`create_variable_set`	Create a new variable set	Confirmation of variable set creation
`create_variable_in_variable_set`	Add a variable to a variable set	Variable creation confirmation
`delete_variable_in_variable_set`	Remove a variable from a variable set	Variable deletion confirmation
`attach_variable_set_to_workspaces`	Attach variable set to workspaces	Attachment confirmation
`detach_variable_set_from_workspaces`	Detach variable set from workspaces	Detachment confirmation
`list_workspace_variables`	List all variables in a workspace	Workspace variable details
`create_workspace_variable`	Create a variable in a workspace	Variable creation confirmation
`update_workspace_variable`	Update an existing workspace variable	Updated variable configuration

Example prompts:

"Create a variable set for database configuration"

Workspace tagging tools

Manage tags for Terraform workspaces to organize and categorize resources.

Tool	Purpose	What it returns
`create_workspace_tags`	Add tags to a workspace	Tag creation confirmation
`read_workspace_tags`	Read all tags from a workspace	List of workspace tags

Stacks tools

Manage Terraform Stacks in an organization.

Tool	Purpose	What it returns
`list_stacks`	Retrieve list of stacks	List of stacks with high level summary
`get_stack_details`	Read full details for a specific stack	Full stack configuration

Example prompts:

"List all the stacks in my organization."
"Show me the details for the dev-environment stack"

Available MCP resources

The Terraform MCP server provides several static read-only guides to the MCP clients to retrieve structured, contextual data. It helps generate standardized Terraform code.

Resource URI	Kind	Description
`/terraform/style-guide`	Resource	Provides access to the official Terraform style guide documentation in markdown format
`/terraform/module-development`	Resource	Comprehensive guide covering module composition, structure, providers, publishing, and refactoring best practices
`/terraform/providers/{namespace}/name/{name}/version/{version}`	Resource Template	Dynamically retrieves detailed documentation and overview for any Terraform provider by namespace, name, and version

Transport protocols

You can set one of the following transport protocols when starting the MCP server so that it operates correctly for your environment.

Transport	Best for	How it works	Usage
`stdio`	Local development and direct integration with MCP clients	Uses standard input/output for JSON-RPC message communication	Automatically used when no specific transport mode is configured
`streamableHTTP`	Remote deployments, distributed setups, production environments	HTTP-based transport with support for both direct HTTP requests	Enable by setting `TRANSPORT_MODE=streamable-http`

Command-line flags

You can add the following flags when you start the server binary.

Flag	Description
`--toolsets`	Comma-separated list of toolsets to enable. Valid values are `registry`, `registry-private`, `terraform`, and the keywords `all` and `default`. The `all` keyword enables every toolset. The `default` keyword enables only the `registry` toolset, and you can combine it with other values, such as `--toolsets=default,registry-private`. When you omit this flag, the server uses `all`. The server ignores invalid values and logs a warning.
`--tools`	Comma-separated list of individual tool names to enable. When you set this flag, only the tools you name are available. You cannot use this flag together with the `--toolsets` flag.
`--log-file`	Path to the log file.
`--log-level`	Log level. Valid values are `trace`, `debug`, `info`, `warn`, `error`, `fatal`, and `panic`. The default is `info`. The `LOG_LEVEL` environment variable overrides this flag.
`--log-format`	Log format. Valid values are `text` and `json`. The default is `text`. The `LOG_FORMAT` environment variable overrides this flag.

You can add the following flags when you start the server with the streamable-http command.

Flag	Description
`--transport-host`	Host to bind the HTTP server to. The default is `127.0.0.1`.
`--transport-port`	Port that the HTTP server listens on. The default is `8080`.
`--mcp-endpoint`	Path for the streamable HTTP endpoint. The default is `/mcp`.
`--heartbeat-interval`	Heartbeat interval for HTTP connections, such as `30s`. The default is `0`, which disables the heartbeat.
`--organization-allowlist`	Comma-separated list of HCP Terraform organization names that can access the HTTP server. The `MCP_ORGANIZATION_ALLOWLIST` environment variable takes precedence over this flag.

Health endpoint

In streamable HTTP mode, the server exposes a /health endpoint that returns a JSON response with the following fields.

Field	Description
`status`	Health status of the server. The value is `ok`.
`service`	Name of the service. The value is `terraform-mcp-server`.
`transport`	Transport protocol. The value is `streamable-http`.
`endpoint`	Path of the streamable HTTP endpoint.
`version`	Version of the running server.

Environment variables

You can set the following environment variables to configure the server behavior.

Variable	Description	Default
`TFE_ADDRESS`	HCP Terraform or Terraform Enterprise address	`"https://app.terraform.io"`
`TFE_TOKEN`	Terraform Enterprise API token	`""` (empty)
`TFE_SKIP_TLS_VERIFY`	Skip HCP Terraform or Terraform Enterprise TLS verification	`false`
`TRANSPORT_MODE`	Set to `streamable-http` to enable HTTP transport (legacy `http`)	`stdio`
`TRANSPORT_HOST`	Host to bind the HTTP server. Set to `0.0.0.0` to bind to all interfaces	`127.0.0.1`
`TRANSPORT_PORT`	HTTP server port	`8080`
`MCP_ENDPOINT`	HTTP server endpoint path	`/mcp`
`MCP_SESSION_MODE`	Session mode: `stateful` or `stateless`	`stateful`
`MCP_ALLOWED_ORIGINS`	Comma-separated list of allowed origins for CORS	`""` (empty)
`MCP_CORS_MODE`	CORS mode: `strict`, `development`, or `disabled`	`strict`
`MCP_RATE_LIMIT_GLOBAL`	Global rate limit (format: `rps:burst`)	`10:20`
`MCP_RATE_LIMIT_SESSION`	Per-session rate limit (format: `rps:burst`)	`5:10`
`ENABLE_TF_OPERATIONS`	Enable destructive Terraform operations	`false`
`MCP_HEARTBEAT_INTERVAL`	Keep-alive long lived streamable HTTP connections (`0` to disable)	`0`
`OTEL_METRICS_ENABLED`	Enable tools metrics using OpenTelemetry	`false`
`OTEL_METRICS_SERVICE_NAME`	Identifies the source of the metrics	`terraform-mcp-server`
`OTEL_METRICS_EXPORT_INTERVAL`	Controls the frequency of metric flushes	`2s`
`OTEL_METRICS_ENDPOINT`	OpenTelemetry collector endpoint	`localhost:4318`
`LOG_LEVEL`	Logging level: `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic`	`info`
`LOG_FORMAT`	Logging format: `text` or `json` (overrides `--log-format` flag)	`text`
`OTEL_METRICS_SERVICE_VERSION`	Server version that the metrics report	The server version
`INSTANA_ENABLED`	Set to `true` to enable Instana instrumentation for the streamable HTTP server	`false`
`INSTANA_SERVICE_NAME`	Service name that the server reports to Instana	`terraform-mcp-server`
`MCP_TLS_CERT_FILE`	Path to the TLS certificate file for the HTTP server	`""` (empty)
`MCP_TLS_KEY_FILE`	Path to the TLS key file for the HTTP server	`""` (empty)
`MCP_ORGANIZATION_ALLOWLIST`	Comma-separated list of organization names that can access the HTTP server	`""` (empty)
`MCP_FORWARD_CLIENT_IP`	Set to `true` to forward the client IP address in the `X-Forwarded-For` header	`false`
`MCP_REMOTE_IP_METHOD`	Method the server uses to determine the client IP address. Valid values are `RemoteAddr`, `X-Real-IP`, and `X-Forwarded-For`.	`RemoteAddr`
`MCP_XFF_TRUSTED_HOPS`	Number of trusted proxy hops, counted from the right of the `X-Forwarded-For` chain. Applies only when `MCP_REMOTE_IP_METHOD` is `X-Forwarded-For`.	`0`
`MCP_REDIRECT_ROOT_URL`	URL that the HTTP server redirects requests for the `/` path to	`""` (empty)
`TF_MCP_SHARED_SECRET`	Shared secret that the server sends in the `X-Tf-Mcp-Secret` header on requests to HCP Terraform or Terraform Enterprise	`""` (empty)

Run type options

The create_run tool supports the following run types by default:

plan_and_apply: Creates a plan and applies it if approved
refresh_state: Refreshes the state without making changes
plan_only: Creates a plan without applying
allow_empty_apply: Allows applying when no changes are detected

When you set ENABLE_TF_OPERATIONS to true, the following additional options become available:

auto_approve: Automatically approves and applies the plan
is_destroy: Creates a destroy plan to remove infrastructure

Destructive operations

Several tools perform destructive operations that can modify or delete infrastructure resources. These tools are disabled by default and require setting ENABLE_TF_OPERATIONS=true:

action_run: Can apply or destroy infrastructure
delete_workspace_safely: Permanently deletes workspaces
force_unlock_workspace force unlocks a workspace that is stuck in a lock
delete_project deletes a project
delete_team permanently deletes a team
Additional run type options in create_run

Warning

When enabled, use these tools with caution as they can permanently modify or destroy infrastructure resources.

Telemetry metrics

When enabled, the Terraform MCP server collects the following metrics:

Type	Emitted metrics	Notes
Standard HTTP server metrics	`http.server.request.body.size` `http.server.response.body.size` `http.server.request.duration`	The server wraps the HTTP mux with `otelhttp.NewHandler(...)` to emit the metrics.
Custom tool metrics	`mcp_tool_calls_total` `mcp_tool_errors_total` `mcp_tool_duration_seconds`	The server uses MCP hooks to call the `BeforeCallTool` and `AfterCallTool` tools, which emit the metrics.
Client metrics	`mcp_client_type_total`	The server counts connections by the name and version of the MCP client.

When you set INSTANA_ENABLED to true, the streamable HTTP server also sends metrics and HTTP request traces to Instana.