Skip to main content

MCP Server Overview and Quickstart

What is MCP?​

The Model Context Protocol (MCP) is an open standard that lets AI agents call external tools through a structured, typed interface instead of shelling out to arbitrary commands. An MCP client (an agent like Claude Code, Claude Desktop, Cursor, or Windsurf) launches an MCP server as a subprocess and talks to it over a JSON-RPC transport; the server exposes a fixed set of named tools with declared input schemas, and the agent calls those tools directly with structured arguments instead of parsing free-form CLI output.

What the Terraback MCP server does​

terraback mcp exposes Terraback's scan, codify, and verify engine as an MCP server over stdio, so an MCP-compatible agent can inventory cloud infrastructure and generate Terraform without shelling out to the CLI. All three cloud providers (AWS, Azure, GCP) are available from v1, through six tools:

ToolPurpose
scan_infrastructureRead-only inventory scan of live cloud resources.
detect_unmanagedDiff a live scan against local Terraform state to find unmanaged resources.
codify_resourceGenerate Terraform HCL and an import block for one resource.
codify_batchGenerate Terraform HCL and import blocks for a batch of resources.
verify_planRun a read-only terraform plan and report drift.
list_supported_resourcesList resource types Terraback can scan and codify.

All six tools are read-only or code-generation-only: none of them import resources into Terraform state or mutate cloud infrastructure. See the Tool Reference for full parameter tables and Agent Workflow for the loop an agent runs to import resources end to end.

Requirements​

  • Python 3.10 or newer (the mcp SDK dependency requires it).
  • Read-only cloud credentials configured in the environment the MCP server process runs in — the tools use the normal ambient credential chain and never accept credentials as arguments. See Security and Credentials.
  • Terraform 1.5 or newer, on PATH, only if you plan to call verify_plan (import blocks require Terraform 1.5+).

Install​

pip install terraback

Installing Terraback pulls in the mcp SDK automatically — no separate install step for the MCP server.

Zero-install trial​

To try the server without installing anything into your environment, run it with uvx:

uvx terraback mcp

Register with an MCP client​

Claude Code​

claude mcp add terraback -- terraback mcp

Project-scoped .mcp.json​

Add the server directly to a project's .mcp.json:

{
  "mcpServers": {
    "terraback": {
      "type": "stdio",
      "command": "terraback",
      "args": ["mcp"]
    }
  }
}

If the project scans Azure resources, add ARM_SUBSCRIPTION_ID to the server's env block. MCP clients spawn servers with a limited environment by default, and azurerm 4.x may need the subscription ID set explicitly rather than inherited from az login context:

{
  "mcpServers": {
    "terraback": {
      "type": "stdio",
      "command": "terraback",
      "args": ["mcp"],
      "env": {
        "ARM_SUBSCRIPTION_ID": "<your-subscription-id>"
      }
    }
  }
}

See Troubleshooting if Azure scans fail with a missing subscription error after adding the server this way.

Verify it is wired up​

terraback --help

should list an mcp command. Running terraback mcp directly starts the server and blocks, speaking JSON-RPC over stdio — it is meant to be launched by an MCP client, not run interactively from a terminal.

First commands an agent will run​

Once the server is registered, a typical first exchange looks like:

  1. list_supported_resources — confirm which resource types Terraback can scan and codify for the provider you care about.
  2. scan_infrastructure — inventory live resources in a given provider + scope (an AWS region, an Azure subscription ID, or a GCP project ID).

From there the agent narrows the scan, generates Terraform with codify_resource or codify_batch, and verifies the result with verify_plan. The full loop, including the safety rules an agent should follow, is documented in Agent Workflow.

Next steps​