Skip to content
fzymgc-house Cluster Docs

Hosted Terraform MCP is read-only; no MCP-triggered TFC runs

Date: 2026-07-03 Status: Accepted Decision: hl-iu87 Deciders: Sean

Context

Section titled “Context”

The hosted Terraform MCP server (hashicorp/terraform-mcp-server) can expose three capability tiers: registry documentation (no credentials), HCP Terraform observation (--toolsets=registry,terraform + a TFE_TOKEN), and — only when ENABLE_TF_OPERATIONS=true — run creation (create_run, whose run_type includes plan_and_apply / is_destroy / auto_approve). The initial ask was “read + plan_only runs.”

Decision

Section titled “Decision”

The hosted Terraform MCP is strictly READ-ONLY: registry docs plus run/workspace observation (list_runs, get_run_details, get_workspace_details, list_workspaces). ENABLE_TF_OPERATIONS stays unset, so run-creation tools are never registered. The TFE_TOKEN is a dedicated tfe_team with custom access runs=read, state_versions=none, variables=none. Registry docs run as a separate zero-credential deployment.

Rationale

Section titled “Rationale”
  • tf/CLAUDE.md already mandates “MUST NOT manually trigger TFC runs via API or MCP tools — GitOps only.” create_run, even plan_only, triggers a run via MCP and violates it.
  • HashiCorp documents that TFC “plan” permission is equivalent to “write” from a security standpoint — “intended to prevent accidental runs, not malicious access.” A plan-scoped token is a UX rail, not a confused-deputy boundary.
  • state_versions=none prevents the token from downloading state or reading sensitive outputs — closing the “plan grants full state read” gap.
  • Apply stays on the GitOps path (PR merge → HCP Terraform auto-apply); the MCP never mutates.

Alternatives Considered

Section titled “Alternatives Considered”
  • Read + plan_only (rejected): violates the tf/CLAUDE.md MUST-NOT, and plan-permission is not a security boundary — negligible safety gain for real blast radius.
  • Full, including apply/destroy (rejected): bypasses HCP Terraform’s auto-apply-on-merge, the analog of the “no kubectl apply” invariant.

Consequences

Section titled “Consequences”
  • Positive: no confused-deputy write path; the token cannot read state/variables; the GitOps apply invariant is fully preserved.
  • Negative: agents cannot trigger even speculative plans via MCP — planning stays on the PR path.
  • Neutral: registry docs need no TFC credential and are served by a separate deployment open to any authenticated caller.