MCP Tool Reference
Terraback's MCP server exposes six tools. Every tool that touches a cloud provider
takes a provider argument (aws, azure, or gcp) and a scope argument whose
meaning depends on the provider:
| provider | scope means |
|---|---|
aws | an AWS region, e.g. "us-east-1" |
azure | an Azure subscription ID |
gcp | a GCP project ID |
AWS tools additionally accept an optional profile (a named AWS CLI profile).
Azure/GCP scope resolution does not currently accept a sub-scope (Azure resource
group, GCP zone) through the MCP layer — scans run against the whole
subscription/project.
Terraback authenticates using each provider's normal ambient credential chain; none of the tools accept credentials as arguments. See Security and Credentials for the recommended read-only roles.
scan_infrastructure
Run a read-only inventory scan of live cloud infrastructure.
Read-only guarantee: never writes Terraform files, never touches state, never imports anything.
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
provider | string (aws | azure | gcp) | yes | - | Cloud provider to scan. |
scope | string | yes | - | Scan boundary: AWS = region (e.g. "us-east-1"), Azure = subscription ID, GCP = project ID. |
types | array<string> | null | no | null | Optional list of resource type names to restrict the scan to, e.g. ["ec2", "aws_vpc"]. Bare names and full registry keys are both accepted. Omit to scan every type registered for the provider. |
tag_filters | object | null | no | null | Optional tag key/value pairs a resource must match on (all pairs required). Resources with no discoverable tags are excluded whenever this is supplied. |
workdir | string | null | no | null (a directory under the system temp directory) | Directory for scratch scan output and the full inventory JSON file. |
profile | string | null | no | null | AWS named profile to use. Ignored for azure/gcp. |
Returns
A summary of the scan: summary.total and summary.counts_by_type. The full
resource list is inlined in the response only up to 200 entries; for larger
inventories the result instead points at an inventory_file on disk — read that JSON
file to see individual resources. See
Troubleshooting for the large-inventory pattern.
Example call
{
"provider": "aws",
"scope": "us-east-1",
"types": ["ec2", "aws_vpc"]
}
detect_unmanaged
Diff a live cloud inventory against local Terraform state to find unmanaged resources.
Read-only guarantee: nothing is written to state and nothing is imported.
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
provider | string (aws | azure | gcp) | yes | - | Cloud provider to scan. |
scope | string | yes | - | Scan boundary: AWS = region, Azure = subscription ID, GCP = project ID. |
state_files | array<string> | yes | - | Paths to one or more LOCAL Terraform state JSON files (e.g. a checked-out terraform.tfstate, or terraform state pull > state.json). Remote backends are not read directly in v1. |
types | array<string> | null | no | null | Optional list of resource type names to restrict the scan to. |
workdir | string | null | no | null | Directory for scratch scan output and the inventory file. |
Returns
The resources found in the live scan that are not present in the given state_files
— the unmanaged resources an agent should target next in the import loop. Work only on
what this tool reports; never touch resources already present in state.
v1 reads local state file paths only. For remote backends (S3, azurerm, GCS,
Terraform Cloud/Enterprise), run terraform state pull > state.json first and pass
that path — see Troubleshooting.
Example call
{
"provider": "azure",
"scope": "00000000-0000-0000-0000-000000000000",
"state_files": ["./state.json"]
}
codify_resource
Generate Terraform HCL and an import block for exactly one resource.
Read-only guarantee: does not import into state - generates code only.
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
provider | string (aws | azure | gcp) | yes | - | Cloud provider. |
scope | string | yes | - | AWS = region, Azure = subscription ID, GCP = project ID. |
type | string | yes | - | Resource type name, bare (e.g. "ec2") or full registry key (e.g. "aws_ec2"). Call list_supported_resources to see valid types. |
resource_id | string | yes | - | The cloud-provider ID (or ARN) of the resource to codify. |
output_dir | string | no | "./generated" | Directory to write the generated Terraform into. |
profile | string | null | no | null | AWS named profile to use. Ignored for azure/gcp. |
Returns
The generated Terraform HCL and its import block for the single requested resource,
written to output_dir. Not subject to the Community license cap — use this tool
freely for one-off resources even on the free tier.
Example call
{
"provider": "aws",
"scope": "us-east-1",
"type": "aws_instance",
"resource_id": "i-0123456789abcdef0",
"output_dir": "./generated"
}
codify_batch
Scan and generate Terraform HCL and import blocks for a batch of resources.
Read-only guarantee: does not import into state - generates code only.
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
provider | string (aws | azure | gcp) | yes | - | Cloud provider. |
scope | string | yes | - | AWS = region, Azure = subscription ID, GCP = project ID. |
types | array<string> | null | no | null | Optional list of resource type names to restrict the batch to. |
tag_filters | object | null | no | null | Optional tag key/value pairs a resource must match on (all pairs required). |
output_dir | string | no | "./generated" | Directory to write the generated Terraform into. |
exclude_managed | boolean | no | false | When true and state_files are given, resources already present in state are fully excluded from the generated output. Requires state_files; if omitted, a warning is returned and nothing is excluded. |
state_files | array<string> | null | no | null | Paths to LOCAL Terraform state JSON files (v1: local paths only, no remote backends). |
profile | string | null | no | null | AWS named profile to use. Ignored for azure/gcp. |
Returns
Generated Terraform HCL and import blocks for the matched batch of resources, written
to output_dir.
On the Community (free) tier, a single call is capped at 25 total resources
(counted after tag_filters are applied, before exclude_managed is applied). If the
requested scope has more resources than that, the tool returns an error and writes
nothing to output_dir:
{
"error": "resource_cap_exceeded",
"total": 143,
"cap": 25,
"counts_by_type": {"aws_ec2": 40, "aws_ebs_volume": 103},
"hint": "..."
}
Narrow the request with types or tag_filters, or upgrade to Professional to lift
the cap — see Licensing and Limits.
Example call
{
"provider": "gcp",
"scope": "my-project",
"types": ["google_storage_bucket"],
"tag_filters": {"env": "prod"},
"output_dir": "./generated"
}
verify_plan
Run a read-only terraform plan against a generated directory and report drift.
Read-only guarantee: never applies, imports, or otherwise mutates state.
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
terraform_dir | string | yes | - | Directory containing the generated .tf files. |
Returns
A drift status of "none", "drift_detected", or "plan_failed", plus a summary
object with imports, adds, changes, and destroys counts, and per-resource lists
(change_resources, add_resources, destroy_resources) for triaging what to fix.
Pending imports are expected and are not drift; adds, changes, and destroys indicate
the generated configuration does not yet match the live resource and should be fixed
before importing.
Requires Terraform 1.5 or newer on PATH — import blocks require Terraform 1.5+.
verify_plan itself needs no cloud credentials beyond what a normal terraform plan
requires, since Terraform re-reads live resource state as part of planning.
Example call
{
"terraform_dir": "./generated"
}
list_supported_resources
List resource types Terraback can scan and codify, grouped by provider.
Read-only guarantee: does not touch any cloud provider.
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
provider | string | null (aws | azure | gcp | null) | no | null | Restrict the listing to one provider. Omit to list all three. |
Returns
The resource type names Terraback can scan and codify, grouped by provider. Use the
returned type names in the types argument of scan_infrastructure, detect_unmanaged,
and codify_batch, and in the type argument of codify_resource.
Example call
{
"provider": "aws"
}
Omit provider (or pass {}) to list resource types for all three clouds.