Skip to main content

Agent Workflow

This is the canonical loop an MCP agent follows to inventory live cloud resources, generate Terraform HCL with import blocks, and verify the result with a read-only terraform plan. All six Terraback MCP tools are read-only or code-generation-only: none of them import into state, apply, or mutate cloud infrastructure. See the Tool Reference for full parameter tables.

Prerequisites​

Check these before starting:

  1. Terraback is installed and on PATH. The MCP server is launched as terraback mcp. If the tools are missing from the client, install with pip install terraback and re-add the server.
  2. Read-only cloud credentials are configured in the environment the MCP server runs in. Tools use the ambient credential chain and never take credentials as arguments: AWS ReadOnlyAccess + SecurityAudit, Azure Reader on the subscription, GCP roles/viewer on the project. See Security and Credentials.
  3. Terraform 1.5 or newer is on PATH if the loop will call verify_plan — it runs terraform init and terraform plan, and import blocks require Terraform 1.5+.

Scope semantics​

Every provider-facing tool takes provider + scope:

  • aws: scope is a region, e.g. "us-east-1". Optional profile selects a named AWS CLI profile.
  • azure: scope is a subscription ID.
  • gcp: scope is a project ID.

Confirm provider and scope with the user before starting the loop.

The canonical loop​

1. Plan coverage​

Call list_supported_resources (optionally with provider) and confirm the resource types the user cares about are supported. Use the returned type names in every later types argument.

2. Inventory​

Call scan_infrastructure with provider and scope. Pass types to narrow the scan — it is much faster than scanning everything. The result contains summary.total and summary.counts_by_type. The full resource list is inlined only up to 200 entries; for larger inventories the result instead points at inventory_file — read that JSON file from disk to see individual resources.

3. Target unmanaged resources (optional)​

If the user already has Terraform state, call detect_unmanaged with provider, scope, and state_files. v1 reads LOCAL state file paths only — for remote backends (S3, azurerm, GCS, Terraform Cloud) run terraform state pull > state.json first and pass that path. Work only on the unmanaged resources it reports; never touch already-managed ones.

4. Codify​

Call codify_batch with provider, scope, types, and an explicit output_dir. Start with a small type subset rather than everything at once. To skip already-managed resources, pass state_files plus exclude_managed: true.

The Community tier caps a single call at 25 total resources. If the tool returns {"error": "resource_cap_exceeded", ...}, nothing was written: narrow the request using types or tag_filters (the error's counts_by_type shows what to cut), or tell the user the Professional tier removes the cap. Use codify_resource for a single known resource ID — it is not capped.

5. Verify​

Call verify_plan with terraform_dir set to the output directory. It returns drift ("none", "drift_detected", or "plan_failed") and a summary of imports, adds, changes, destroys.

6. Fix drift until clean​

Pending imports are expected and are not drift. Adds, changes, and destroys are problems:

  • Read change_resources / add_resources / destroy_resources from the result, open the corresponding .tf files in output_dir, and fix the specific attributes causing the diff.
  • If drift is "plan_failed", read the returned error output, fix the invalid HCL or provider config, and re-run.
  • Re-run verify_plan after each fix. Repeat until drift is "none".

7. Hand off​

Summarize for the user: files written (list the .tf files in output_dir), resource counts by type, and any remaining warnings from the tool results. State clearly that nothing has been imported or applied yet, and give the next command (terraform apply performs the imports).

Safety rules​

  • Never edit the IDs inside generated import blocks — they are the contract between the code and the live resource.
  • Prefer regenerating a resource (codify_resource / codify_batch) over hand-editing whole files; hand-edit only targeted attributes when resolving drift.
  • Never run terraform apply unless the user explicitly asks for it. Every Terraback MCP tool is read-only or code-generation-only by design — applying is a deliberate, separate step the user takes.
  • Do not invent tool parameters. The parameter tables in the Tool Reference are the authoritative contract for what each tool accepts.
  • Tool Reference: full parameter tables and example calls for every tool used in this loop.
  • Security and Credentials: read-only roles to configure before running the loop.
  • Licensing and Limits: what changes about step 4 on the Community tier.
  • Troubleshooting: fixes for the most common issues encountered mid-loop (missing ARM_SUBSCRIPTION_ID, old Terraform, large inventories, remote state backends).