# hashicorp/terraform-mcp-server architecture

> Architecture diagram of the GitHub repository hashicorp/terraform-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hashicorp/terraform-mcp-server
- Repository: https://github.com/hashicorp/terraform-mcp-server

## Overview

Terraform MCP Server exposes Terraform Registry and HCP Terraform capabilities to MCP clients. The main workflow is client request → transport/server → tool selection and middleware → Registry or TFE API → MCP response; clients can connect over stdio or Streamable HTTP. Toolsets filter available tools, while session-scoped clients handle backend access. Resources provide Terraform guides, and HTTP-mode metrics support monitoring. Edges follow sampled calls or README-documented capabilities; unsampled subsystem links are omitted where their wiring is not shown.

Main entry points: [`pkg/mcp-mark3labs/server.go`](https://github.com/hashicorp/terraform-mcp-server/blob/main/pkg/mcp-mark3labs/server.go) (MCP server), [`pkg/mcp-mark3labs/http.go`](https://github.com/hashicorp/terraform-mcp-server/blob/main/pkg/mcp-mark3labs/http.go) (HTTP transport), [`pkg/cli/flags.go`](https://github.com/hashicorp/terraform-mcp-server/blob/main/pkg/cli/flags.go) (CLI startup), [`pkg/mcp-official/tools/tools.go`](https://github.com/hashicorp/terraform-mcp-server/blob/main/pkg/mcp-official/tools/tools.go) (Tool registration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["MCP entrypoints"]
  node_cli["CLI startup<br/>[flags.go]"]
  node_http["HTTP transport<br/>[http.go]"]
  node_stdio["Stdio transport<br/>[stdio.go]"]
  node_server["MCP server<br/>[server.go]"]
  node_official["Official SDK server<br/>[server.go]"]
end

subgraph group_features["MCP capabilities"]
  node_registrytools["Public Registry tools"]
  node_tfetools["Terraform operations"]
  node_resources["Guide resources<br/>[resources.go]"]
  node_officialtools["SDK tool registry"]
  node_officialtfe["SDK TFE tools<br/>[teams_get_tool.go]"]
  node_toolregistration["Tool registration<br/>[tools.go]"]
end

subgraph group_backend["Backend access"]
  node_httpclient["Registry HTTP client<br/>[registry_client.go]"]
  node_tfeclient["TFE session client<br/>[tfe_client.go]"]
end

subgraph group_policy["Session and controls"]
  node_filter["Toolset filtering<br/>[filter.go]"]
  node_middleware["Request middleware<br/>[middleware.go]"]
  node_metrics["OTel metrics<br/>[otelmetrics.go]"]
end

node_user(("MCP client"))
node_registryapi{{"Terraform Registry"}}
node_tfeapi{{"HCP Terraform / TFE"}}

node_user -->|"connects via HTTP"| node_http
node_user -->|"connects via stdio"| node_stdio
node_cli -->|"starts HTTP"| node_http
node_cli -->|"starts stdio"| node_stdio
node_http -->|"serves MCP"| node_server
node_stdio -.->|"serves MCP"| node_server
node_server -->|"gates tools"| node_filter
node_server -->|"registers resources"| node_resources
node_server -->|"registers tools"| node_registrytools
node_server -->|"registers tools"| node_tfetools
node_official -->|"registers tools"| node_toolregistration
node_toolregistration -->|"registers tools"| node_officialtools
node_toolregistration -->|"registers tools"| node_officialtfe
node_official -->|"filters tools"| node_filter
node_registrytools -->|"requests client"| node_httpclient
node_httpclient -.->|"queries"| node_registryapi
node_officialtools -->|"requests client"| node_httpclient
node_tfetools -->|"requests client"| node_tfeclient
node_officialtfe -->|"requests client"| node_tfeclient
node_tfeclient -.->|"calls API"| node_tfeapi
node_http -.->|"configures controls"| node_middleware
node_cli -->|"sets up metrics"| node_metrics

click node_cli "https://github.com/hashicorp/terraform-mcp-server/blob/main/pkg/cli/flags.go"
click node_http "https://github.com/hashicorp/terraform-mcp-server/blob/main/pkg/mcp-mark3labs/http.go"
click node_stdio "https://github.com/hashicorp/terraform-mcp-server/blob/main/pkg/mcp-mark3labs/stdio.go"
click node_server "https://github.com/hashicorp/terraform-mcp-server/blob/main/pkg/mcp-mark3labs/server.go"
click node_official "https://github.com/hashicorp/terraform-mcp-server/blob/main/pkg/mcp-official/server.go"
click node_filter "https://github.com/hashicorp/terraform-mcp-server/blob/main/pkg/toolsets/filter.go"
click node_registrytools "https://github.com/hashicorp/terraform-mcp-server/blob/main/pkg/tools/registry/search_providers.go"
click node_tfetools "https://github.com/hashicorp/terraform-mcp-server/tree/main/pkg/tools/tfe"
click node_resources "https://github.com/hashicorp/terraform-mcp-server/blob/main/pkg/resources/resources.go"
click node_officialtools "https://github.com/hashicorp/terraform-mcp-server/blob/main/pkg/mcp-official/tools/registry/search_providers.go"
click node_officialtfe "https://github.com/hashicorp/terraform-mcp-server/blob/main/pkg/mcp-official/tools/tfe/teams_get_tool.go"
click node_toolregistration "https://github.com/hashicorp/terraform-mcp-server/blob/main/pkg/mcp-official/tools/tools.go"
click node_httpclient "https://github.com/hashicorp/terraform-mcp-server/blob/main/pkg/client/registry_client.go"
click node_tfeclient "https://github.com/hashicorp/terraform-mcp-server/blob/main/pkg/client/tfe_client.go"
click node_middleware "https://github.com/hashicorp/terraform-mcp-server/blob/main/pkg/client/middleware.go"
click node_metrics "https://github.com/hashicorp/terraform-mcp-server/blob/main/pkg/otelmetrics/otelmetrics.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_http,node_stdio,node_server,node_official,node_user toneBlue
class node_registrytools,node_tfetools,node_resources,node_officialtools,node_officialtfe,node_toolregistration toneAmber
class node_httpclient,node_tfeclient toneMint
class node_filter,node_middleware,node_metrics toneRose
class node_registryapi,node_tfeapi toneIndigo
```

## Components

### MCP entrypoints

- [CLI startup](https://github.com/hashicorp/terraform-mcp-server/blob/main/pkg/cli/flags.go): `pkg/cli/flags.go`
- [HTTP transport](https://github.com/hashicorp/terraform-mcp-server/blob/main/pkg/mcp-mark3labs/http.go): `pkg/mcp-mark3labs/http.go`
- [Stdio transport](https://github.com/hashicorp/terraform-mcp-server/blob/main/pkg/mcp-mark3labs/stdio.go): `pkg/mcp-mark3labs/stdio.go`
- [MCP server](https://github.com/hashicorp/terraform-mcp-server/blob/main/pkg/mcp-mark3labs/server.go): `pkg/mcp-mark3labs/server.go`
- [Official SDK server](https://github.com/hashicorp/terraform-mcp-server/blob/main/pkg/mcp-official/server.go): `pkg/mcp-official/server.go`

### MCP capabilities

- [Public Registry tools](https://github.com/hashicorp/terraform-mcp-server/blob/main/pkg/tools/registry/search_providers.go): `pkg/tools/registry/search_providers.go`
- [Terraform operations](https://github.com/hashicorp/terraform-mcp-server/tree/main/pkg/tools/tfe): `pkg/tools/tfe`
- [Guide resources](https://github.com/hashicorp/terraform-mcp-server/blob/main/pkg/resources/resources.go): `pkg/resources/resources.go`
- [SDK tool registry](https://github.com/hashicorp/terraform-mcp-server/blob/main/pkg/mcp-official/tools/registry/search_providers.go): `pkg/mcp-official/tools/registry/search_providers.go`
- [SDK TFE tools](https://github.com/hashicorp/terraform-mcp-server/blob/main/pkg/mcp-official/tools/tfe/teams_get_tool.go): `pkg/mcp-official/tools/tfe/teams_get_tool.go`
- [Tool registration](https://github.com/hashicorp/terraform-mcp-server/blob/main/pkg/mcp-official/tools/tools.go): `pkg/mcp-official/tools/tools.go`

### Backend access

- [Registry HTTP client](https://github.com/hashicorp/terraform-mcp-server/blob/main/pkg/client/registry_client.go): `pkg/client/registry_client.go`
- [TFE session client](https://github.com/hashicorp/terraform-mcp-server/blob/main/pkg/client/tfe_client.go): `pkg/client/tfe_client.go`

### Session and controls

- [Toolset filtering](https://github.com/hashicorp/terraform-mcp-server/blob/main/pkg/toolsets/filter.go): `pkg/toolsets/filter.go`
- [Request middleware](https://github.com/hashicorp/terraform-mcp-server/blob/main/pkg/client/middleware.go): `pkg/client/middleware.go`
- [OTel metrics](https://github.com/hashicorp/terraform-mcp-server/blob/main/pkg/otelmetrics/otelmetrics.go): `pkg/otelmetrics/otelmetrics.go`

### Other components

- **MCP client**
- **Terraform Registry**
- **HCP Terraform / TFE**

## Connections

- MCP client → HTTP transport: connects via HTTP
- MCP client → Stdio transport: connects via stdio
- CLI startup → HTTP transport: starts HTTP (evidence: `pkg/cli/flags.go`)
- CLI startup → Stdio transport: starts stdio (evidence: `pkg/cli/flags.go`)
- HTTP transport → MCP server: serves MCP (evidence: `pkg/mcp-mark3labs/http.go`)
- Stdio transport → MCP server: serves MCP
- MCP server → Toolset filtering: gates tools (evidence: `pkg/mcp-mark3labs/server.go`)
- MCP server → Guide resources: registers resources (evidence: `pkg/mcp-mark3labs/server.go`)
- MCP server → Public Registry tools: registers tools (evidence: `pkg/mcp-mark3labs/server.go`)
- MCP server → Terraform operations: registers tools (evidence: `pkg/mcp-mark3labs/server.go`)
- Official SDK server → Tool registration: registers tools (evidence: `pkg/mcp-official/server.go`)
- Tool registration → SDK tool registry: registers tools (evidence: `pkg/mcp-official/tools/tools.go`)
- Tool registration → SDK TFE tools: registers tools (evidence: `pkg/mcp-official/tools/tools.go`)
- Official SDK server → Toolset filtering: filters tools (evidence: `pkg/mcp-official/server.go`)
- Public Registry tools → Registry HTTP client: requests client (evidence: `pkg/tools/registry/search_providers.go`)
- Registry HTTP client → Terraform Registry: queries
- SDK tool registry → Registry HTTP client: requests client (evidence: `pkg/mcp-official/tools/registry/search_providers.go`)
- Terraform operations → TFE session client: requests client (evidence: `pkg/tools/tfe/search_private_providers.go`)
- SDK TFE tools → TFE session client: requests client
- TFE session client → HCP Terraform / TFE: calls API
- HTTP transport → Request middleware: configures controls
- CLI startup → OTel metrics: sets up metrics (evidence: `pkg/cli/flags.go`)
